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Preface 


The OS/2™ Presentation Manager™ provides a rich and powerful set of applica¬ 
tion programming interfaces which, to a newcomer, can appear rather complex 
and confusing. Many OS/2 application developers use software tools (such as 
application generators) or languages which shield them from the complexities of 
the application programming interface and serve as a useful productivity aid. The 
majority of these are designed specifically for text based applications that require 
only the graphical user interface and it is currently necessary for programs to use 
the Graphics Programming Interface directly in order to exploit the full graphics 
capabilities of the OS/2 Presentation Manager. This book is written for C program¬ 
mers wishing to use the OS/2 Presentation Manager GPI and Dev functions for 
providing high quality text and graphics output to displays and printers. It is 
intended to be used along with the relevant IBM™ and Microsoft™ Reference 
Manuals and Online Reference, and is not a substitute for these. 

My aim in writing this book is, as far as possible, to provide answers 
(illustrated by programming examples) to any questions that Application Devel¬ 
opers may have concerning the GPI and Dev functions. Rather than providing a 
tutorial description, I have concentrated on making the description of each topic 
as comprehensive as possible. Chapter 1 provides an introduction and explains 
how to output simple graphics and text to displays and printers. The remaining 
chapters provide an in-depth description of each subject, illustrated where 
appropriate by examples consisting of simple, self-contained program functions. 
Also included in the main body of the text is a description of the underlying GPI 
Architecture to assist readers in understanding a particular function. 

Some familiarity with OS/2 Presentation Manager Programming funda¬ 
mentals by the reader is assumed. The reader should, as a minimum, be able to 
write a basic Presentation Manager application in C to create a message queue 
and standard window, with a window procedure that processes the messages. 
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PREFACE 


Although the main subject of this book is graphics, it is written for non-mathe¬ 
maticians. Where mathematics is essential (e.g., in the treatment of transforms), 
it is kept to a minimum. Both GPI and Dev functions are described, and where 
there is overlap with other components (such as the Win and Prf functions), a 
description of these is also provided. 

This book is based on IBM OS/2 Version 1.3 and includes a discussion of Version 

2 . 0 . 
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Introduction: Simple Text and Graphics Output 


This chapter describes how to generate simple GPI text and graphics output to 
displays and printers, and introduces a number of important rules and concepts 
required for the more advanced topics described in subsequent chapters. 

The GPI (Graphics Programming Interface) enables a Presentation Manager 
Application Program to produce high quality text and graphics output to a variety 
of output devices. These include both displays and printers and a number of 
special purpose’ virtual output devices such as bitmaps and MetaFiles. Output 
can, in fact, be directed at any of the following: 

• A window on a display screen. 

• A printer or plotter device. 

• A memory bitmap (i.e., a memory pixel array). 

• A memory MetaFile (for recording a picture for interchange). 

• An information only context useful for querying device information 
without incurring all of the memory overheads associated with dis¬ 
playing output. 

• Any other device or virtual device for which a Presentation Driver 
(i.e., Presentation Manager Device Driver) exists. 


GPI GRAPHICS SUBSYSTEM STROCTURE 

The GPI graphics subsystem is illustrated in Figure 1-1 and consists of a hierar¬ 
chy of layers below the application. These are the GPI layer, the Graphics Engine, 
the Presentation Driver, and, in the case of certain devices such as printers, the 
appropriate OS/2 Kernel Device Driver. Current Display Presentation Drivers 
communicate directly with the display adapter, whereas Printer Presentation 
Drivers convert the low level graphics calls presented at their Device Driver 

1 



2 


OS/2 PRESENTATION MANAGER GPI 



Figure 1.1 Graphics Subsystem. 


Interface (DDI) into raw printer data, and pass this to the OS/2 Kernel Print 
Device Driver. 

Data ownership is also encapsulated within the different layers. The GPI layer 
owns the Presentation Space (PS), the Graphics Engine owns the Device Context 
(DC), and the Presentation Driver owns an extension of the Device Context called 
the Device Drawing Context (DDC). 

Although Figure 1—1 correctly illustrates GPI graphics output for displays and 
directly attached printers, the situation when printing via the spooler is rather 
more complex (see chapter 12). 


PRESENTATION spaces mb dewice contexts 

GPI function calls are targeted at a Presentation Space (PS) associated (i.e., 
linked) with a Device Context (DC). The DC identifies both the target output 
device and the instance of that device (such as a printer or display window) to 
which the output is directed. The DC stores such items as the current drawing 
attribute values (color, mix, line style, etc.). Memory MetaFiles and Bitmaps also 
receive output via DCs of the appropriate type associated with the target PS. 

The PS stores presentation space environment attributes and resources. Its 
purpose is to retain this information between application calls and across associ¬ 
ations and disassociations of the PS with different DCs. PS data is normally, but 
not exclusively, device independent and a PS may also optionally retain (i.e., store) 
the entire picture. 

For the majority of applications that require only a subset of the GPI functions, a 
special PS called a Micro-PS should be used. This has a smaller memory overhead 
than a Normal-PS. Also, where large numbers windows each require a PS and DC 
for a short sequence of operations, a variation of the Micro-PS called a cached 
Micro-PS may be used to allow a PS and DC to be shared between different windows, 
(see chapter 2 for a detailed description of device contexts and presentation spaces.) 
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OUTPUT T0 A DISPLAY WINDOW AND PRINTER 

Output of a simple text string (say) to a display window requires the following 
steps: 

1. Obtain a DC for the window. 

2. Create a PS and associate the PS and DC. 

3. Draw the text string to the PS. 

4. Destroy the PS if no longer required. 

This is illustrated by the function OutputToWindow in Figure 1-2. Note that 
WinOpenWindowDC can be used only once to open the window DC which then 
remains open until the window is destroyed. Thereafter the DC handle can be 
obtained using WinQueryWindowDC. Note also that a DC can be associated only 
with a single PS, and GpiCreatePS (with the GPI_ASSOC option) will therefore 
fail if the window DC is already associated. 

Performing an equivalent operation for a printer (or plotter) requires the 
following steps: 

1. Query the printer DRIVDATA (driver data). 

2. Open a Device Context (DC) for the printer. 

3. Create a PS and associate the PS and DC. 

4. Issue a 'Start Document' escape to the device. 

5. Draw the text string to the PS. 

6. Issue an 'End Document' escape to the device. 

7. Destroy the PS if no longer required. 

8. Close the Printer DC if no longer required. Note that a printer DC 
(unlike a window DC) can be destroyed. 

This is illustrated by the function OutputToPrinter in Figure 1-3. The Out¬ 
putToWindow function in Figure 1-2 could have been implemented in a variety of 
different ways. A PS type of GPIT_MICRO was, in fact, used to create a Micro-PS, 
whereas a Normal or cached Micro-PS could have been used instead. 

A number of different character string functions are also available. The function 
used, GpiCharStringAt, draws a character string starting from a specified posi¬ 
tion. The GPI maintains a current drawing position attribute internally that is 
updated by most GPI output operations (including GpiCharStringAt). This attri¬ 
bute can also be set directly from an application using GpiSetCurrentPosition or 
GpiMove. Many GPI functions, including GpiCharString, draw from (and update) 
the current position. The function GpiCharStringAt is therefore equivalent to: 

GpiSetCurrentPosition; and 

GpiCharString. 

These two functions could therefore have been used in place of the single 
GpiCharStringAt function. Note that in the function OutputToWindow, PU_ARBI- 
TRARY page units are specified together with a default PS page size of zero. 
PU_ARBITRARY page units cause the specified PS page to be scaled to fit the 




4 


OS/2 PRESENTATION MANAGER GP1 


available device output area while preserving the aspect ratio (such that a circle 
remains a circle). In the case of a display window, the available device output area 
is assumed to be constant and equal to the screen size. Either or both PS page 
dimensions may be defaulted by specifying as zero, in which case they are 
determined by the dimensions of the device output area (but note that for a printer 
this is NOT the same as the current form size). 

Other page units are also available. An application wishing to draw in device units 
should specify page units of PU_PELS whereas PU_TWIPS, PUJLOENGLISH, 
FUHIENGLISH, PU_LOMETRIC, and PUHIMETRIC are available for drawing 
objects of specified size in millimeters or inches. The OutputToPrinter function uses 
PS page units of PU_LOMETRIC (i.e., 0.1mm) and the PS page size is selected to 
match the 8.5x11 inch printer form. PUJLOMETRIC page units were chosen be¬ 
cause the form size information returned by DevQueryHardcopyCaps (used later) is 
in millimeters. The precise PS page size values are generally unimportant for page 
units other than PU_ARBITRARY (but very small values should be avoided). 

Chapter 12 describes how the queue name (pszQueue), printer name (pszPrin¬ 
ter), driver name (pszDriver), and device name (pszDevice) used by OutputToPrin¬ 
ter can be queried from the INI file. For the moment, however, hardcoded string 
constants (e.g., “LASER1” or “LPTIQ”) copied from the Print Manager dialogs will 
suffice. Note that some printer drivers (e.g., IBM4019) support only a single device 
and require a NULL device name, whereas others (e.g., LASERJET.HP™ 
LaserJet™ Plus) have a dot qualified extension that must be specified as the device 
name. 


OUTPUTTING A TEXT FILE 

Consider now the requirement to output a text file first to a display window and 
then to a printer. Assume the text file has already been read into a memory buffer 
(e.g., using DosAllocate—DosOpen—DosRead—DosClose). 

Clearly, the entire contents of the buffer are unlikely to fit on the display screen 
simultaneously and scrolling must therefore be provided. The function Dis- 
playTextBuffer in Figure 1—4 illustrates how this may be accomplished (this 
function can, in fact, be substituted for GpiCharStringAt in the OutputToWindow 
function described earlier). 

DisplayTextBuffer begins by erasing the window and resetting the default view 
matrix before querying the font metrics. The font metrics provide the character 
width and height values needed to convert the row and column scroll offsets into 
world (i.e., drawing) coordinates. WinQueryWindowRect is used to determine the 
top window coordinate (in pels) and GpiConvert converts this to world coordinates. 
The function GpiSetDefaultViewMatrix is used to provide the translation required 
by the (IRow, ICol) scroll parameters and GpiCharStringAt is used to draw each 
row of text. Output begins at the start of the text, works downward, and termi¬ 
nates when the bottom of the window is reached. 

The requirements of a function that outputs text to a printer are slightly 
different from those of one that outputs to a display. Clearly, the printer is unable 
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to support scrolling and, instead, the complete document must be printed on 
multiple pages with page ejects at the page boundaries and suitable margins on 
each page. The function PrintTextBuffer in Figure 1-5 illustrates how this may be 
accomplished (this function can in fact be substituted for GpiCharStringAt in the 
OutputToPrinter function described earlier). 

PrintTextBuffer is, in fact, quite similar to BisplayTextBuffer with scrolling 
removed. DevQueryHardcopyCaps is used to determine the form (or paper) dimen¬ 
sions in millimeters and these are multiplied by ten to convert them to 
PU_LOMETRIC page units of 0.1 mm. GpiSetGraphicsField is used to provide the 
clipping required by the right margin (the other margins are obtained by the 
positioning of the text). Each time the bottom of the page is reached, 
DevEscapq/BEVESCJNEWFRAME is used to perform a page eject. Note that 
PrintTextBuffer requires that the DEVESC_STARTBOC and DEVESC_ENDDOC 
DevEscape functions are issued by the invoker. 


SIMPLE GRAPHICS OUTPUT 

Graphics differ from text in that they use a bottom left origin, whereas text 
normally uses top left as illustrated above. 

Orawingj Primitives and Attributes 

Graphics drawing is accomplished using drawing primitive functions (e.g., GpiL- 
ine, GpiCharStringAt) and drawing attribute setting functions (e.g., GpiSetColor 
GpiSetMix). The drawing primitives specify the output operation to be performed 
and the drawing attribute functions control the drawing attributes (e.g., color, mix) 
of the subsequent drawing primitives. As mentioned earlier, many drawing prim¬ 
itives start at, and update, the current drawing position for the PS, while others 
specify their own starting position. The drawing primitives and attributes can be 
divided into five groups as follows: 

• Characters and Text. 

• Lines and Curves. 

• Filled Areas (or patterns). 

® Markers (e.g., points on a graph). 

• Image and BitBlt pixel operations. 

Area functions are used for drawing closed figures with a defined shape that are 
filled using a specified fill pattern. Markers are typically used to draw the points 
on a graph and BitBlt functions are used to transfer rectangular pixel images 
between memory bitmaps and raster devices. Image functions are similar to BitBlt 
but transfer images from application memory. 

Some drawing primitive operations combine drawing primitives and/or attri¬ 
butes from more than one group. An example is GpiFullArc which draws a circle 
or ellipse, optionally filled with an area fill pattern. Another example is GpiBitBlt 
which can combine both Image and Area attributes to construct the target image. 
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Each primitive group has its own attribute bundle (or structure) containing the 
attributes for that particular primitive type. Instances of color and mix attributes 
appear in all attribute bundles and are known as global attributes/ Other bundle 
attributes appear in only a single bundle. Examples of the latter are the area fill 
pattern and character direction. Other general attributes apply to all primitives 
and are not part of any attribute bundle. Examples of these are the Current 
Position, Model Transform, and Viewing (clip) Limits. 

As mentioned above, the appearance (color, size, etc.) of GPI graphics output is 
controlled by the bundle attributes for the primitive type concerned, which may be 
set to the required values before drawing. For characters, the CHARBUNDLE 
(character bundle) is used; for lines, the LINEBUNDLE (line bundle) is used; for 
areas, the AREABUNDLE (area bundle) is used; for markers, the M A RKERBl IN - 
DLE (marker bundle) is used; and for BitBlt and image, the IMAGEBUNDLE 
(image bundle) is used. It is not essential to set the bundle attributes before 
drawing as the default value can be used for most bundle attributes (bundle 
attributes are reset to default by GpiResetPS). Note, however, that for most 
devices, the default character set is a raster font and several of the CHARBUNDLE 
attributes are ignored for character mode CM_MODE 1 raster characters. For those 
devices that provide an outline font as the default, the character box attribute 
(height and width) must be set to the required character box size in world coordi¬ 
nates to ensure that correctly sized characters are obtained. Character angle, 
direction, and shear attributes can be defaulted for both outline and raster fonts. 

The functions DrawText, DrawLines, Dr aw Area, DrawMarkers, and WCBitBlt 
in Figures 1—6 to 1-10 set each of the appropriate bundle attributes before 
performing the text, line, area, marker or BitBlt output operation. Note that in the 
case of DrawLines, certain of the LINEBUNDLE attributes that apply exclusively 
to paths are not referenced by this function. These are discussed in chapter 3. In 
the WCBitBlt example, the bitmap used would typically have been created using 
the icon editor and included in the .rc file using a statement of the form: 

BITMAP ID_BITMAP3 mybmap.bmp 

where ID_BITMAP3 is a numeric constant (e.g., #define ID_BITMAP3 3) specified 
as the WCBitBlt (and GpiLoadBitmap) usBitmapId parameter. 

Simple Transformations 

The GPI transform functions enable rotation, scaling, and translation of subse¬ 
quent output to be controlled by a transform matrix attribute. 

There are a number of different transforms to choose from but in general, the 
model transform can be varied during drawing for the purpose of picture construc¬ 
tion (i.e., picture modeling) and the default viewing transform should be used for 
scaling and scrolling and remain constant for the complete picture. The examples 
in this section use the model transform but apply equally to the default viewing 
transform (although rotations other than 90 degrees would not normally be 
applied to the whole picture). 



INTRODUCTION: SIMPLE TEXT AND GRAPHICS OUTPUT 


7 


The function Rotate in Figure 1-11 illustrates how a figure can be rotated about 
a given point in the figure (note that rotation about the origin would produce an 
additional undesired translation). The function Scale in Figure 1-12 illustrates 
how a figure can be scaled relative to a given point in the figure (note that scaling 
relative to the origin would produce an additional undesired translation). The 
function Translate in Figure 1-13 illustrates how a figure can be translated by a 
specified amount. 

The Transform helper functions/ GpiRotate, GpiScale, and GpiTranslate, sim¬ 
plify transform construction but are not absolutely essential. It is possible to 
calculate the correct matrix values and obtain the required result by a sequence 
of set transform matrix operations (see chapter 7). 


BUIES MO CONCEPTS 

The OPI Graphics Models Picture and Environmenf/Resouroes 

The GPI model views the graphics functions as belonging to one of two groups: 

• Picture Functions; or 

• PS Environment and Resource Functions. 

Picture Functions are drawing primitive functions (such as line, arc, character 
string) and drawing attribute setting functions (such as set color, set mix) used to 
construct the picture and vary the drawing attributes as the picture is drawn. Any 
function that can cause a graphics order to be built and stored in a retained 
graphics segment (see chapter 9) can be regarded as a picture function. In addition, 
there are a small number of picture functions for non-retained use only that do not 
add an order to a retained segment. These are: 

GpiBitBlt; 

GpiPaintRegion; 

GpiSetPel; and 

WinDraw functions (e.g., WinDrawText). 

Except for the default attribute functions (which are environment attributes), 
picture functions are those functions described in chapter 3. All other functions are 
Environment and Resource Functions (or neither). 

Environment and Resource Functions are functions that create and load re¬ 
sources (such as logical fonts and color tables) or functions that establish environ¬ 
ment attributes (such as graphics field and default viewing transform). These 
should generally be established before the picture is drawn and remain unchanged 
during drawing (although it is permissible to incrementally create and load 
additional resources as they are needed). Of course it is quite possible for an 
application to vary the resources and environment attributes during picture 
construction. However, apart from this being unnecessary because of the rich set 
of picture functions available, there are other good reasons for not doing so. It is 
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extremely useful to have functions such as Graphics Field and Default Viewing 
Transform available exclusively for defining rectangular clipping and scaling for 
the complete picture. Also, if the picture is to be recorded in a MetaFile for 
interchange, an SAA conforming MetaFile will not be produced if environment 
attributes or resources are modified during picture construction. Such a MetaFile 
will not properly conform to the interchange architecture and, although it will 
normally interchange successfully with other OS/2 Presentation Manager sys¬ 
tems, picture information will be lost, or errors will occur, if interchange is 
attempted with other products that support this architecture. 

Retained and Nora-Retained Graphics 

An application that chooses to store its graphics picture in application memory and 
issue every GPI function call required for picture reconstruction each time a 
repaint is required is called a non-retained application. 

As mentioned earlier, it is also possible for a PS to store the entire graphics 
picture. The same GPI functions are used for retained picture construction but 
with the PS in 'Retain’ mode, such that GPI picture functions are accumulated as 
drawing orders in PS segment store rather than being displayed and discarded. 
These drawing orders are grouped together in objects known as graphics seg¬ 
ments. An entire retained graphics picture can then be repainted from retained 
graphics segment store by a single GpiDrawChain call. 

Retained graphics would be useful for a picture transmitted for remote display 
in a network, or for any local application requiring this type of picture storage 
capability. Also, when the PS stores the entire picture, it is very simple to 
disassociate the PS from a window DC and reassociate it with a different DC, 
making it easy to print the picture or to record it in a MetaFile. 

Retained graphics segments can be called from other retained segments or 
drawn by a non-retained application using the GpiDrawSegment and 
GpiCallSegmentMatrix functions. It is possible to use a mixture of non-retained 
and retained graphics, with a non-retained application drawing retained segments 
for those picture objects that are drawn multiple times with different positions and 
sizes. 

It is also possible to edit existing retained segments. Functions exist to enable 
retained segments to be reopened and elements (i.e., groups of one or more 
drawing orders) to be inserted and deleted as required. 

Correlation and Boundary Accumulation 

In addition to providing the ability to draw graphics to a variety of output devices 
or DC types, the GPI provides functions that return information about a picture 
to the application. 

Boundary Accumulation is useful for determining the smallest bounding rectan¬ 
gle into which the entire picture will fit. This can be regarded as the 'high water 
mark’ of the picture coordinates and is useful for scaling the picture to fit an output 
rectangle (see for example, the function SubpictureMetaFile in chapter 11) and for 
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performing optimizations. For example, if part of the window needs to be repainted 
and the area to be repainted does not intersect the bounding rectangle then no 
drawing (other than an erase) need occur. The picture boundary data can also be 
used to predict whether a particular transform operation will result in coordinate 
overflow (see chapter 7). 

Correlation is provided for interactive graphics. A frequent end-user operation 
is that of selecting an object on a display screen by pointing using a mouse and 
screen pointer or cursor. The object might then, for example, be dragged to a 
different position, changed to a different color or deleted by the user. To identify 
the object, the application must determine which primitive or primitive group from 
the picture corresponds to the screen coordinates of this selection. 

Correlation assists this operation by establishing a movable correlation rectan¬ 
gle (which an application would typically move with the pointer) and identifying 
to the application which drawing primitives or retained graphics segments inter¬ 
sect this rectangle. This correlation rectangle is known as the pick aperture. 


Coordinates 


GPI Coordinate Limits 

Many GPI functions have one or more coordinate pairs as a parameter. In most 
cases the coordinates are defined in a space known as world coordinate space, but 
some functions require their coordinates to be specified in an intermediate space 
above the device (e.g., the PS page) whereas others are specified directly in device 
coordinates. World coordinates, as they are called, and other intermediate coordi¬ 
nates are transformed by the various GPI transforms down to the device, produc¬ 
ing output in device coordinates. These non-device coordinates are specified as 32 
bit integers that must be in the (28 bit) range 0xF8000000-0x07FFFFFF (i.e., 
-134217728 to 134217727). Furthermore, when transformed to device space, the 
resultant device coordinates must be in the (16 bit) range OxFFFFSOOO- 
OxOOOQ7FFF (-32768 to 32767). This 16 bit restriction also applies to device 
coordinates that are specified directly. These restrictions are necessary to avoid 
coordinate overflow. 

Retained Segment and Metafile Coordinate Limits 

When GPI drawing primitives are used to construct a retained graphics picture or 
recorded in a MetaFile, graphics drawing orders containing primitive coordinates 
are built and accumulated in graphics segments. Depending on the coordinate 
format option specified with GpiCreatePS, drawing order coordinates are either 
stored in long (4 byte) format which is the default, or short (2 byte) format. 
Coordinates stored in short format require less memory for retained picture and 
MetaFile storage but it is the responsibility of the application to ensure that 
truncation of 32 bit primitive coordinates to 16 bit order coordinates does not result 
in loss oi data (a large positive value greater than 32767 could appear negative after 
truncation). For performance reasons, no checking is performed by the system. 
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Rectangle Boundaries 

Many GPI functions require a rectangle (i.e., two pairs of coordinates) as a 
parameter. Examples are the box primitive and clip region functions. There is a 
fairly simple rule to determine which rectangle boundaries are inclusive (i.e., part 
of the rectangle interior), and which are exclusive (i.e., outside the rectangle). If 
defined in device coordinates, rectangle coordinates are inclusive at the bottom 
and left boundaries and exclusive at the top and right boundaries. When two 
boundaries are the same, the rectangle is null. If defined in any coordinate space 
other than device space, rectangle coordinates are inclusive at all boundaries. 


Staying Responsive and Multi-threaded Applications 

In an environment such as OS/2 that supports multiple applications, it is import¬ 
ant that all applications are well-behaved and remain responsive to the end user. 
This is ensured if applications always complete their message queue processing 
and return to process the next message from the queue in less than 0.5 seconds. 
Graphics output in particular, including drawing to a queued printer DC, can take 
a considerable time to complete, and all but very simple drawing operations should 
therefore be performed on a separate asynchronous thread. 

Although most GPI applications are likely to be multi-threaded, the same GPI 
PS may not be used re-entrantly on different threads (i.e., by issuing simultaneous 
GPI function calls). If this is attempted, a GPI error (PMERR_PS__BUSY) may 
occur. The one exception to this is the GpiStopDraw function which can be used to 
stop the drawing operation being performed on a different thread. Typically, this 
is used to modify the operation as a result of a new message received from the 
message queue. See chapter 9 for a description of GpiStopDraw. 

FIXED lumbers 

A number of GPI functions have parameters of type FIXED. Examples are char¬ 
acter box attribute and transform matrix elements in the earlier examples. FIXED 
numbers are signed 4 byte numbers with a notional decimal point between the 
middle two bytes. This representation can be viewed as the original number 
multiplied by 65.536. For example: 


2.5 

is 0x00028000; 

2.0 

is 0x00020000; 

1.0 

is 0x00010000; 

0.5 

is 0x00008000; 

0.25 

is 0x00004000; 

0.125 

is 0x00002000; 

etc. 
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FIXED numbers obey all the normal rules of binary arithmetic and negative values 
are simply the twos complement of the corresponding positive number. For example: 

2.25 is 0x00024000; and 
“2.25 is OxFFFDCOOO. 

A MAKEFIXED macro is available to assist fixed number construction. 

Error Handling 

In the interest of simplicity, no error checking is included in the examples provided 
in this chapter, although full error checking is included in the examples through- 
out the remaining chapters of this book. 

Ideally, all applications should check all return codes from Base OS/2 and 
Presentation Manager function calls. It is, however, an application designer's 
choice as to how much error checking should be included, and there is a case for 
omitting this checking for simple functions (e.g., simple drawing attribute and 
primitive functions as GpiSetColor and GpiLine). Error checking is particularly 
important during application development and testing. It is recommended as an 
absolute minimum, that all returned handles, and all return values from functions 
that create, load, and delete objects or resources, should always be examined for 
error. The memory and performance overhead incurred error checking is likely to 
be small, particularly if the return codes can be held in registers. 

Whereas Base OS/2 calls (e.g., DosAllocSeg) return a zero for ok or a non-zero 
error number, Presentation Manager functions generally return NULL or zero 
(GPI_ERROR) for error and a non-zero function value for ok. Where zero repre¬ 
sents a valid return value, an alternative value such as minus one (GPI_AL- 
TERROR) or -255 (CLR_ERROR) is used to indicate an error. Many GPI functions 
(e.g., GpiSetColor) return a BOOL: 

TRUE (1) - ok; and 

FALSE (0) - error. 

Note that the symbol TRUE should only be used with extreme caution by an 
application as TRUE is defined as ONE, and does not have the same meaning as 
true in the C language which means any non-zero value. 

The GPI drawing primitives (e.g., GpiLine) return a 'LONG' having one of three 
values: 

GPIJERROR (0) - error; 

GPI_OK (1) - ok; and 

GPI_HITS (2) - a correlate hit occurred. 

If correlation is not enabled, a code simplification may be achieved by casting 

this LONG to a BOOU (this technique is used by a number of examples in this 
book). 
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If a Presentation Manager function returns error, an error code providing more 
information about the error is logged internally and can be retrieved together with 
a severity value using WinGetlastError. 

PM Error codes are defined in PMERR.H and base OS/2 error codes in 
BSEERR.H. Severities are defined in PMWIN.H as one of the following: 


SEVERITY_NOERROR 
SEVERITY JVARNING 
SEVERITY_ERROR 
SEVERITYJSEVERE 
SEVERITY_UNRECOVERABLE 


0x0000; 
0x0004; 
0x0008; 
0x0000; and 
0x0010. 


The macros ERRORIBERROR and ERRORIDSEV are useful for extracting 
the error code and severity from the ERRORIB value returned by 
WinGetLastError. 

Logged errors of severity SEVERITY_WARNING indicate a minor error that the 
system was able to correct. No error is returned by the function concerned and 
such warnings’ are therefore only visible to an application if a function such as 
WinGetLastError is issued in the absence of an error return code. Warnings are, 
in fact, sometimes logged internally by the system during normal operation and 
are no cause for concern. 

Errors of severity SEVERITY_ERROR and higher are more serious and cause 
the function concerned to give a return code of error. 

WinGetErrorlnfo can be used to obtain yet more information about a logged 
error Like WinGetLastError, this too provides the error code and severity and also 
provides a null terminated text string describing the error. In addition, if the 
logged error was PMERR_BASE_ERROR then the error occurred in an underlying 
Base OS/2 call that resulted from processing the original request. In this case, the 
Base OS/2 error number is also provided by WinGetErrorlnfo. Note that 
WinGetErrorlnfo should always be followed by WinFreeErrorlnfo to release the 
memory. 

Use of WinGetErrorlnfo is illustrated by the function BisplayPMError in Figure 
1—14. This can be used when an error is returned by any Presentation Manager 
function call. It displays a message box containing: 

Hexadecimal PM error code; 


Hexadecimal Severity value; 

Becimal Base OS/2 Error number (if PM error is 
PMERR_BASE_ERROR); and 

PM Error Message string. 

For retained graphics drawing functions, correlation functions, and functions that 
process an order buffer (i.e., GpiPutBata and GpiElement), an additional function 
is provided for obtaining error information: 
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GpiErrorSegmentData 

For retained segment functions, this returns the segment name and element 
number at which the error occurred. For GpiPutBata or GpiElement, it returns 
the byte offset into the buffer at which the error occurred. 


optowind.c */ 


VOID OutputToWindowCHWND hwnd) 

{ 

/* Obtain a Device Context (DC) for the window. */ 

/* Create a Gpi Presentation Space (PS) and associate the PS and DC. */ 

/* Draw the text string to the PS. */ 

/* Destroy the PS. */ 

/* */ 

/* inputs: hwnd window handle */ 

/* */ 

^define GPIWTEXT "Gpi Window text" 

^define NGPIWTEXT (LONG)(sizeof(GPIWTEXT)-1) 

hdc ; /* display window DC handle */ 

HPS hps ; /* PS handle */ 

SIZEL sizlPSPage ; /* PS page size */ 

POINTL ptlPosn ; /* drawing position */ 

/****************************************************************************** , 

/* */ 

/* Obtain a Device Context (DC) for the window. */ 

/* * / 

/******************************************************************************j 

/* query Window DC */ 

hdc = WinQueryWindowDC(hwnd); /* -window handle */ 

if (hdc == NULL) /* open window DC if NULL */ 

hdc = WinOpenWindowDC(hwnd); /* -window handle */ 

/****************************************************************************** . 

'* */ 

/* Create a Gpi Presentation Space (PS) and associate the PS and DC */ 

/* */ 

/**************************************************************************^^ i 

sizlPSPage.cx = OL; /* set PS page dimensions */ 

sizlPSPage.cy = OL; /* and create Gpi PS */ 

hps - GpiCreatePS( WinQueryAnchorBlock(hwnd) /* -anchor block handle */ 

. hdc /* -DC handle */ 

, &sizlPSPage /* -PS page size */ 

, PU_ARBITRARY /* -options */ 

GPIF_DEFAULT 
GPIT_MICR0 
GPIA_ASSOC 

); 


Figure 1.2 OutputToWindow Function 




14 


OS/2 PRESENTATION MANAGER CPI 


/* 



*/ 

/* Draw the text string to the PS. 



*/ 

/* 

kr ** *•*•** **-jl 

^************************>1 

*/ 

r **** / 

ptlPosn.x = 200 ; 

/* 

set drawing position and 

*/ 

ptlPosn .y = 200; 

/* 

draw character string to 

PS */ 

GpiCharStringAt( hps 

/* 

-PS handle 

*/ 

, &ptlPosn 

/* 

-starting position 

*/ 

, NGPIWTEXT 

/* 

-number of characters 

*/ 

, GPIWTEXT 
); 

/* 

-character string 

*/ 

/ ^^^^*^*^^^^^**^^*^^*^*******^^*^**^*^^*, 

********** 

f ************************. 

r * y 1 

/* 



*/ 

/* Destroy the PS. 



*/ 

/* 

*★★*★★**** 

************************** 

*/ 

e * * * * y 


/* 

destroy the PS 

*/ 

GpiDestroyPSC hps ); 

/* 

-PS handle 

*/ 


return; 


Figure 1.2 (continued) 


/* optoprtr.c */ 

VOID OutputToPrinter( HAB hab 

, PSZ pszQueue 
, PSZ pszPrinter 
, PSZ pszDriver 
, PSZ pszDevice 
) 


/* 

Query 

the printer driver data. 



*/ 

/* 

Open a 

Device Context (DC) for the printer. 

*/ 

/* 

Create 

a Gpi Presentation Space 

(PS) 

and associate the PS and DC. 

*/ 

/* 

Issue 

a ’Start Document’ escape 

to the printer. 

*/ 

/* 

Draw the text string to the PS. 



*/ 

/* 

Issue 

an ’End Document’ escape to the 

printer. 

*/ 

/* 

Destroy the PS. 



*/ 

/* 

Cl ose 

the Printer DC. 



*/ 

/* 





*/ 

/* 

inputs: 

hab anchor block 

handl e 

*/ 

/* 


pszQueue Queue name 

e.g. 

“LPT1Q”) 

*/ 

/* 


pszPrinter Printer name 

e.g. 

“PRINTER1" 

*/ 

/* 


pszDriver Driver name 

e.g. 

“LASERJET” or “IBM4019" 

*/ 

/* 


pszDevice Device name 

e.g. 

“HP LaserJet II” 

*/ 

/* 




(or NULL for IBM4019) 

*/ 

/* 





*/ 


Figure 1.3 OutputToPrinter Function. 
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/****************************************************************************** / 

/* */ 

/* Pa ge width and height represent form size of letter (8.5 x 11 inches) */ 
/* in PILLOMETRIC units of 0.1 mm. */ 

/* */ 

/**************************************************************************+.***/ 


#define 

PSPAGEWIDTHP 

2159L 




#define 

PSPAGEHEIGHTP 

2794L 




#define 

PDOCNAME 

“Print Job” 




#define 

PDOCNAMELEN 

(LONG)sizeof(PDOCNAME) 




#define 

GPIPTEXT 

“Gpi Print Text” 




#define 

NGPIPTEXT 

(LONG)(sizeof(GPIPTEXT) 

-1) 


PDRIVDATA 

pdrivData 



/* 

pointer to DRIVDATA 

*/ 

DEVOPENSTRUC dopData 



/* 

DEVOPENSTRUC structure 

*/ 

SIZEL 

sizlPSPage 


/* 

PS page size 

*/ 

POINTL 

ptlPosn 



/* 

drawing position 

*/ 

LONG 

1 Length 



/* 

1ength 

* / 

USHORT 

usJobld 



/* 

job id 

* / 

HDC 

hdc 



/* 

DC handle 

*/ 

HPS 

hps 



/* 

PS handle 

*/ 


/******************************************************** 

/* 

/* Query the printer driver data. 

/* 

/******************************************************** 


**********************j 
*/ 
*/ 
*/ 

********************** j 


/* query DRIVDATA length */ 

1 Length = DevPostDeviceModes( hab /* -anchor block handle */ 

> NULL /* -DRIVDATA pointer */ 

, pszDriver /* -driver name */ 

, pszDevice /* -device name */ 

» pszPrinter /* -printer name */ 

, DPDM_QUERYJ0BPR0P /* -options */ 

pdrivData = mal1oc((SHORT)lLength); /* allocate DRIVDATA memory */ 

_ _ /* query DRIVDATA */ 

DevPostDeviceModes( hab /* -anchor block handle */ 

, pdrivData /* -DRIVDATA pointer */ 

, pszDriver /* -driver name */ 

, pszDevice /* -device name */ 

, pszPrinter /* -printer name */ 

, DPDM_QUERYJOBPROP /* -options */ 


/* ' 

. * / 
I* Open a Device Context (DC) for the printer. */ 


/ 

/************************************************^^^^^^^^ 


*******/ 


Figure 1.3 (continued) 
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/* set DevOpenDC params 

*/ 




/* and open a printer DC 

*/ 

dopData.pszLogAddress 

= 

pszQueue; 

/* -logical address 

*/ 

dopData.pszDriverName 

= 

pszDriver; 

/* -driver name 

*/ 

dopData.pdriv 

= 

pdrivData; 

/* -DRIVDATA 

*/ 

dopData.pszDataType 

= 

“PM_Q_STD”; 

/* -data type 

*/ 

dopData.pszComment 

= 

“Gpi Print’’; 

/* -comment 

*/ 

dopData.pszQueueProcName 

= 

NULL; 

/* -queue proc name (default) 

*/ 

dopData.pszQueueProcParams 

= 

“C0L=C XFM=0"; 

/* -queue proc params 

*/ 

dopData.pszSpoolerParams 

= 

NULL; 

/* -spooler params 

*/ 

dopData.pszNetworkParams 

= 

NULL; 

/* -network params (not used) 

*/ 

hdc = DevOpenDCC hab 



/* -anchor block handle 

*/ 

, 0D_QUEUED 



/* -DC type 

*/ 




/* -token 

*/ 

; 9L 



/* -number of data elements 

*/ 

, (PDEVOPENDATA)&dopData 

/* -open DC data 

*/ 

, NULL 
); 



/* -compatible DC handle 

*/ 

free(pdrivData); 



/* free DRIVDATA memory 

*/ 


/****************************************************************************** f 
/* */ 
/* Create a Gpi Presentation Space (PS) and associate the PS and DC */ 
/* */ 
/*★★★**★*★★*★**★*★****★****★****★★**★*****★**★*★★*★*★★★★*★★★★*★★★★*★★★★*★★*★*★*/ 


sizlPSPage.cx = PSPAGEWIDTHP; 

/* 

set PS page dimensions 

*/ 

sizlPSPage.cy = PSPAGEHEIGHTP; 

/* 

and create Gpi PS 

*/ 

hps = GpiCreatePS( hab 

/* 

-anchor block handle 

*/ 


, hdc 

/* 

-DC handle 

*/ 


, &sizlPSPage 

/* 

-presentation page size 

*/ 


, PU LOMETRIC 

/* 

-options 

*/ 


GPIF DEFAULT 




GPIT MICRO 





GPIA ASSOC 





); 

/**************************************ic********i<:**-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k/ 

/* */ 

/* Issue a ’Start Document’ escape to the printer. */ 

/* */ 

I******************************************************************************/ 



/* start document escape 

*/ 

DevEscape( hdc 

/* -DC handle 

*/ 

, DEVESC STARTDOC 

/* -escape code 

*/ 

, PDOCNAMELEN 

/* -size of document name 

*/ 

, PDOCNAME 

/* -null terminated doc name 

*/ 

, NULL 

/* -size of op data (not used) 

*/ 

, NULL 

/* -output data (not used) 

*/ 


); 


/******★*★★*★*★*★★★★★*★★**★★★★*****★*★★★**★★★★*★*★•*'*★★■*'*****★*★* *★★★★★*******★*/ 
/* */ 

/* Draw the text string to the PS. */ 

/* */ 

/*********************************************************************** 


Figure 1.3 (continued) 





INTRODUCTION: SIMPLE TEXT AND GRAPHICS OUTPUT 


17 


ptlPosn.x = 1000; 

/* 

set drawing position and 

*/ 

ptlPosn.y = 1000; 

/* 

draw character string to 

PS*/ 

GpiCharStringAt( hps 

/* 

-PS handle 

*/ 

, &ptlPosn 

/* 

-starting position 

*/ 

, NGPIPTEXT 

/* 

-number of characters 

*/ 

, GPIPTEXT 

/* 

-character string 

*/ 



2L; 

/* end document escape 

*/ 

( hdc 

/* -DC handle 

*/ 

, DEVESC_ENDD0C 

/* -escape code 

*/ 

, 0L 

/* -length of input data (0L) 

*/ 

, NULL 

/* -input data (not used) 

*/ 

, &1Length 

/* -size of output data (2L) 

*/ 

. ( PBYTE)&usJobId 

/* -returned job id 

*/ 



/* destroy the PS */ 

GpiDestroyPSC hps ); /* - PS handle */ 



_ /* Close the DC */ 

DevCloseDC( hdc ); /* -DC handle */ 

return; 

} 


Figxire 1.3 (continued) 
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/* disptext.c */ 

VOID DisplayTextBuffer(HPS hps, HWND hwnd, PCH pchData, LONG IRow, LONG 1 Col ) 

{ 

/* Display a buffer of text, typically read from a text file, in the */ 

/* specified window (via the specified PS) using the current font. */ 

/* */ 

/* The following assumptions are made: */ 

/* */ 

/* 1. The specified PS is associated with a DC for the specified window */ 

/* */ 

/* 2. The text contains no null characters, each row is terminated by */ 

/* carriage return (OxOD) and line feed characters (OxOA) and the */ 

/* final row is terminated by end-of-file (OxlA). */ 

/* */ 

/* inputs: hps PS handle */ 

/* hwnd window handle */ 

/* 1 Row row origin (scrolling offset) */ 

/* IColumn colum origin (scrolling offset) */ 

/* pchData pointer to text buffer */ 

/* */ 


LONG 

POINTL 


1 Count 
ptlPosn 


FONTMETRICS fmMetrics 


PCH 

PCH 

RECTL 


pchRow 
pchRowEnd 
r c 1 W i n d 


static MATRIXLF matlfDV 


/* character count */ 
/* coordinate position */ 
/* FONTMETRICS structure */ 
/* pointer to start of row */ 
/* pointer to end of row */ 
/* window rectangle */ 
/* default view matrix */ 


0x10000, 0L, 0L, 0L, 0x10000, 0L, 0L, 0L, 1L ); 


/* 

/* Erase the window and reset the default view matrix. 
/* 


*/ 

*/ 

*/ 


GpiErase(hps ); 


/* 

-PS handle 

*/ 

matlfDV.1M31 = 0L; 
matlfDV.1M32 = 0L; 
GpiSetDefaultViewMatrix( 

hps 

/* 

-PS handle 

*/ 

, 

9 L 

/* 

-count of matrix elements 

*/ 

, 

&matlfDV 

/* 

-transform matrix 

*/ 


TRANSFORM REPLACE 

/* 

-options 

*/ 


); 


/* 

*/ 

/* Query the metrics of the current font. 

*/ 

/* 

*/ 


GpiQueryFontMetrics( hps 

/* -PS handle 

*/ 

, (L0NG)sizeof(FONTMETRICS) 

/* -length of metrics 

*/ 

, &fmMetrics 

/* -returned metrics 

*/ 


); 


F igure 1 .4 DisplayTextBuffer Function. 
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/* 

/* Query the window coordinates in pels 

and use this to determine 

the 

*/ 

*/ 

/* maximum window y coordinate in world 

coordinates. 


*/ 

/* Initialize the x and y starting coordinates to top left of the 

window 

*/ 

/* and the row pointer to the buffer start. 


*/ 

/* 

/•k-k'kk'k-k-k-k-k-k-kk'k'k-k-k'kk-k-k'k-k-kk-k-k'k-k-k'k'k-k-k-kk'k-k'k'ki 

^★****★***★****★****★***★*•>1 

r ********, 

*/ 
k-k-k-k j 

WinQueryWindowRect( hwnd 

/* -window handle 


*/ 

, &rclWind 

/* -window rectangle 


*/ 

j , 

ptlPosn.x = OL; 
ptlPosn.y = rclWind.yTop; 

GpiConvert( hps 

/* -PS handle 


*/ 

, CVTC DEVICE 

/* -source 


*/ 

, CVTC WORLD 

/* -target 


*/ 

, 1L 

/* -number of coordinates 

*/ 

, &ptlPosn 

/* -coordinate array 


*/ 


); 


ptlPosn.x = OL; 

ptlPosn.y -= fmMetrics.1MaxAscender; 
pchRow = pchData; 


/* 

/* Set the Default View Matrix translation to provide the specified 
/* (row, column) scroll offsets. 


*/ 

*/ 

*/ 

*/ 


matlf DV . 1 M31 = -1 Col 
mat 1fDV.1M32 = 1 Row 


fmMetrics.1AveCharWi dth ; 

(fmMetrics.1MaxBaselineExt+fmMetr i cs.lExternalLeading); 


( hps 

/* 

-PS handle 

*/ 

, 9 L 

/* 

-count of matrix elements 

*/ 

, &matlfDV 

/* 

-transform matrix 

*/ 

, TRANSF0RM_REPLACE 

/* 

-options 

*/ 


/* Locate newline, carriage return or end of file to find end of first row. 
/* 


pchRowEnd = strpbrk(pchRow, “\n\r\xlA”); 


/* 

/* 

While end-of-file has not been reached 

perform the following: 

*/ 

*/ 

/* 

1. 

Draw characters in current row. 

*/ 

/* 

2. 

Process carriage return and newline 

at row end. 

*/ 

/* 

3. 

If bottom of window is reached then 

break (to improve performance). 

k / 

/* 

4. 

Locate end of next row. 

*/ 

/* 




*/ 


Figure 1.4 (continued) 
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while (*pchRow != OxlA ) 

{ 

ICount = pchRowEnd-pchRow; 


GpiCharStringAt( hps 

/* -PS handle 

*/ 

, &ptlPosn 

/* -starting position 

*/ 

, ICount 

/* -number of characters 

*/ 

, pchRow 

/* -character string 

*/ 


pchRow += ICount; 

while (*pchRow = ’\r’ || *pchRow == ’\n’) 

i f (*pchRow == '\r’ ) 
ptlPosn.x = 0L; 
else 

ptlPosn.y - = (fmMetrics.1MaxBaselineExt + fmMetrics.1 ExternalLeading ) ; 
pchRow++; 


if (ptl Posn.y-fmMetrics.1MaxDescender+1Row*(fmMetrics.1MaxBaselineExt 
+fmMetrics.1 ExternalLeading) < OL) 

break; 

pchRowEnd = strpbrk( pchRow, "\n\r\xlA”); 

} 

return; 


Figure 1.4 (continued) 


/* 


VOID PrintTextBuffer(HPS hps, PCH pchData) 

/* Output a buffer of text, typically read from a text file, to the 
/* printer (via the specified PS) using the current font. 


printext 


/* The foilwing assumptions are made: 
/* 


/* 1. The specified PS is associated with a printer DC. 

/* 

/* 2. The PS Page Units are PU_L0METRIC. 

/* 

/* 3. The text contains no null characters, each row is terminated by 

/* carriage return (OxOD) and line feed characters (OxOA) and the 
/* final row is terminated by end-of-file (OxlA). 

/* 

/* 4. 'start document’ and 'end document’ escapes are issued by the caller 

/* before and after invocation. 

/* 


/* inputs: 
/* 

/* 


hps PS handle 

pchData pointer to text buffer 


.c */ 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


/* 


*/ 


/* margins are defined in PU_LOMETRIC units of 0.1 mm 
/* 


*/ 

*/ 


Figure 1.5 PrintTextBuffer Function. 
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#define 

TOPMARGIN 120L 



#define 

BOTTOMMARGIN 200L 



#define 

LEFTMARGIN 150L 



#define 

RIGHTMARGIN 100L 



HDC 

hdc 

/* DC handle 

*/ 

LONG 

1 Count 

/* character count 

*/ 

LONG 

1NumForms 

/* number of forms 

*/ 

LONG 

1 FormHeight 

/* form height mm 

*/ 

LONG 

1 FormWidth 

/* form width mm 

*/ 

LONG 

1FormTopClip 

/* form top clip limit mm 

*/ 

LONG 

1 FormBottomCl i p 

/* form bottom clip limit mm 

*/ 

LONG 

1FormLeftClip 

/* form left clip limit mm 

*/ 

POINTL 

ptlPosn 

/* coordinate position 

*/ 

PHCINF0 

phciForms 

/* pointer to forms array 

*/ 

FONTMETRICS fmMetrics 

/* FONTMETRICS structure 

*/ 

PCH 

pchRow 

/* pointer to start of row 

*/ 

PCH 

pchRowEnd 

/* pointer to end of row 

*/ 

LONG 

i 

/* array index 

*/ 

RECTL 

rcl Fi el d 

/* graphics field 

*/ 


/******************************************************************************/ 


/* * / 

I* Query the handle of the associated DC. */ 

/* */ 

/************************j(*********it****ic*******-k*ic***ic*i<:i(i(**ic-k-k-k-k-k-k-k-k-k-k'k'k-k-k-k-k-k/ 

hdc = GpiQueryDevice(hps); /* -PS handle */ 

/******************************************************************************/ 
/* */ 

/* Query the metrics of the current font. */ 

/* */ 

/***************************************************************** 

GpiQueryFontMetrics( hps /* -PS handle */ 

, (L0NG)sizeof(FONTMETRICS) /* -length of metrics */ 

, &fmMetrics /* -returned metrics */ 

); 


/-*•*■*•*■*•*•*■ ***************************************-k-k-k-k-k-k-k-k-k*-k-k-k-k-k-k-k-k**-k*-k-k-k*-k-k-)<:-k-k-k/ 


/* */ 

/* Determine the paper size and clip boundaries of the current form. */ 

/* 1. Query number of forms. */ 

/* 2. Allocate Memory. */ 

/* 3. Query the forms. */ 

/* 4. Locate the current form. */ 

/* 5. Convert the forms information from mm to PU_LOMETRIC units of 0.1 mm. */ 

/* 6. Free the memory. */ 

/* */ 


/****************************************************★**★**********************/ 


Figure 1.5 (continued) 
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INumForms = DevQueryHardcopyCaps( hdc 

, OL 
, OL 
, NULL 
); 


1* 

-DC handle 



*/ 

/* 

-first form 

requested 

*/ 

/* 

-number of 

forms 

requested 

*/ 

/* 

-returned HCINFO 

forms array 

*/ 


phciForms = mal1oc((SHORT)lNumForms*sizeof(HCINFO)); 


DevQueryHardcopyCaps( hdc 
, OL 

, INumForms 
, phciForms 
); 


/* -DC handle */ 
/* -first form requested */ 
/* -number of forms requested */ 
/* -returned HCINFO forms array */ 


for ( i =0; i <1NumForms - 1 && !( phci Forms[ i ].flAttributes & HCAPS_CURRENT); i++); 


1FormHeight 
1FormWidth 
1FormT opClip 
1FormBottomClip 
1FormLeftClip 


= phciForms[i].cy * 10 ; 

= phciForms[i].cx * 10 ; 

= phciForms[i].yTopClip * 10; 

= phciForms[i].yBottomClip * 10 ; 
= phciForms[i].xLeftClip * 10 ; 


free(phciForms); 


/* 

/* Set graphics field to clip at right margin. 
/* 


*/ 

*/ 

*/ 


rclField.xLeft = 0L; 

rclField.yBottom = 0L; 

rclField.yTop = IFormHeight; 

rclField.xRight =!FormWidth - RIGHTMARGIN; 

GpiSetGraphicsField( hps /* -PS handle */ 

, &rclField /* -graphics field */ 

); 


/* */ 

/* Initialize drawing position to top left and row pointer to buffer start. */ 
/* */ 


ptlPosn.y = min(1FormHeight-TOPMARGIN, 1FormTopClip) - fmMetrics.1MaxAscender; 
ptlPosn.x = max(LEFTMARGIN, 1FormLeftClip); 
pchRow = pchData; 


/* */ 

/* Locate newline, carriage return or end of file to find end of first row. */ 
/* */ 


Figure 1.5 (continued) 
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pchRowEnd = strpbrk(pchRow, “\n\r\xlA”); 

/******************★***********************************************************/ 


/* */ 

/* While end-of-file has not been reached perform the following: */ 

/* 1. Draw characters in current row. */ 

/* 2. Process carriage return and newline at row end. */ 

/* 3. If at bottom of page issue 'new frame’ escape & reset drawing position.*/ 

/* 4. Locate end of next row. */ 

/* */ 


/********^******^************************************************^*************/ 

while (*pchRow != OxlA ) 

{ 

ICount = pchRowEnd-pchRow; 


GpiCharStringAt( hps 

/* 

-PS handle 


*/ 

, &ptlPosn 

/* 

-starti ng 

position 

*/ 

, ICount 

/* 

-number of 

characters 

*/ 

, pchRow 

/* 

-character 

string 

*/ 


); 

pchRow += 1 Count; 

while (*pchRow == ’\r’ || *pchRow == ’\n') 

{ 

if (*pchRow == ’\r’ ) 

ptlPosn.x = max(LEFTMARGIN, 1FormLeftClip); 
el se 

ptlPosn.y - = (fmMetrics.1MaxBaselineExt + fmMetrics.1 ExternalLeading); 
pchRow++; 

} 


if (ptlPosn.y -fmMetrics.1MaxDescender < max(BOTTOMMARGIN, 1 FormBottomCl i p)) 
{ 


hdc 

/* -DC handle 

*/ 

DEVESC NEWFRAME 

/* -escape code 

*/ 

OL 

/* -length of input data (OL) 

*/ 

NULL 

/* -input data (not used) 

*/ 

NULL 

/* -size of output data (OL) 

*/ 

NULL 

/* -output data (not used) 

*/ 


); 

ptlPosn.y = mindFormHeight-TOPMARGIN, 1FormTopClip) 
- fmMetrics.1MaxAscender; 

} 


pchRowEnd = strpbrk( pchRow, “\n\r\xlA”); 

} 

return; 


Figure 1.5 (continued) 
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/ drawtext.c */ 

VOID DrawText(HPS hps) 

{ 

/* Reset the PS, erase the window, set the CHARBUNDLE (character bundle) */ 

/* attributes and draw some text. */ 

/ * * / 

/* Note that for most devices the default character set is a raster font */ 

/* and several CHARBUNDLE attributes are ignored for CM_M0DE1 raster */ 

/* characters. For those devices that provide a vector font as default */ 

/* the character box attribute should be set to the required character */ 

/* height in world coordinates. Character angle, direction and shear can */ 

/* be defaulted. */ 

/* */ 

/* inputs: hps PS handle */ 

/* */ 

POINTL ptlPosn ; /* coordinate position */ 

SIZEF sizfxCharBox ; /* character box size */ 

GRADIENTL gradlAngle ; /* character angle */ 

POINTL ptlShear ; /* character shear angle */ 


/* 

/* Reset the PS and erase the window. 
/* 





GpiResetPS( hps 

, GRES_ALL 
); 

GpiErase(hps ) ; 


/* -PS handle 
/* -options 

/* -PS handle 


*/ 

*/ 

*/ 



Figure 1.6 DrawText Function. 
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GpiSetColor( hps 

, CLR_BLUE 
); 


GpiSetBackColor( hps 

, CLR_YELLOW 
); 

GpiSetMix( hps 

, FM_OVERPAINT 
); 


GpiSetBackMix( hps 

, BM_OVERPAINT 
); 


GpiSetCharSet( hps 

, LCID_DEFAULT 
); 


GpiSetCharMode( hps 

, CM_M0DE1 
); 

sizfxCharBox.cx = MAKE FIX ED(50,0); 

sizfxCharBox.cy = MAKEFIXEDC50,0); 

GpiSetCharBoxC hps 

, &sizfxCharBox 
); 


gradlAngle.x = 2L; 
gradlAngle.y = 1L; 

GpiSetCharAngle( hps 

, &gradlAngle 
); 


GpiSetCharDirecti on( hps 

, CHDIRN_LEFTRIGHT 
); 


ptlShear.x = 1L; 
ptlShear.y = 5L; 

GpiSetCharShear( hps 

, &ptlShear 
); 


/* set foreground color */ 
/* -PS handle */ 
/* -foreground color */ 

/* set background color (ignored */ 
/* with background mix BM_LEAVEAL0NE)*/ 
/* -PS handle */ 
/* -background color */ 

/* -set foreground mix */ 
/* -PS handle */ 
/* -foreground mix mode */ 

/* set background mix (normally */ 
/* BM_LEAVEAL0NE for simple text) */ 
/* -PS handle */ 
/* -background mix mode */ 

/* set character set (normally */ 
/* default for simple text) */ 
/* -PS handle */ 
/* -character set */ 

/* set character mode (normally */ 
/* default CM_M0DE1 for simple text) */ 
/* -PS handle */ 
/* -character mode */ 

/* set character box (ignored for */ 
/* raster fonts; required for all */ 
/* outline fonts in all modes) */ 
/* -PS handle */ 
/* -character box (50 x 50) */ 

/* set character angle (ignored for */ 
/* character mode CM_M0DE1 and */ 
/* raster fonts; normally default */ 
/* (1,0) for simple text) */ 
/* -PS handle */ 
/* -character angle */ 

/* set character direction (ignored */ 
/* (for character mode CM_M0DE1 and */ 
/* raster fonts; normally default */ 
/* CHRDIRN_LEFTRIGHT for simple text)*/ 
/* -PS handle */ 
/* -character direction */ 

/* set character shear (ignored for */ 
/* character mode CM_M0DE1 and */ 
/* raster fonts; normally upright */ 
/* (0,1) for simple text) */ 
/* -PS handle */ 
/* -character shear */ 


Figure 1.6 (continued) 
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' k ’ k ' k ' k ' k ' k ' k - k ' k - k ' k ' k'k j 
*/ 
*/ 
*/ 


ptlPosn.x = 50L; 
ptlPosn.y = 100L; 

GpiMove( hps 

, &ptlPosn 
); 

GpiCharString( hps /* -PS handle */ 

, (LONG)(sizeof(“some text”)-l) 

, “some text” 


return; 

} 

Figure 1.6 (continued) 


/* -PS handle */ 

/* -coordinate position */ 



/* drawline.c */ 


VOID DrawLines(HPS hps) 

{ 

/* Reset the PS, erase the window, set the LINEBUNDLE (line bundle) */ 

/* attributes and draw some lines (note that those line bundle attributes */ 

/* which apply only to paths are not referenced by this function). */ 

/* */ 

/* inputs: hps PS handle */ 

/* */ 


POINTL ptlPosn ; /* coordinate position */ 



GpiResetPS( hps 

, GRES_ALL 
); 

GpiErase(hps ) ; 


/* -PS handle 
/* -options 

/* -PS handle 


*/ 

*/ 

*/ 



Figure 1.7 DrawLines Function. 
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GpiSetColor( hps 

/* -PS handle 


*/ 

, CLR_BLUE 
); 

/* -foreground 

col or 

*/ 

GpiSetMix( hps 

/* -PS handle 


*/ 

, FM OVFRPAINT 
); 

/* -foreground 

mix mode 

*/ 

GpiSetLineWidth( hps 

/* -PS handle 


*/ 

, 0x00010000 
); 

/* -cosmetic line width (1.0) 

*/ 

/* 


r ***************- 

k~k -k J 

*/ 

/* Draw some 1ines. 



*/ 

/* 

k'k'k-k'k'k-k'k-k-k-kick'k-k-k'k-k-k'k-k'k-k-i 

r ***************. 

*/ 

*■** / 

ptlPosn.x = 50L; 
ptlPosn.y = 100L; 

GpiMove( hps 

/* -PS handle 


*/ 

, &ptlPosn 
) ; 

/* -coordinate 

position 

*/ 

ptlPosn.x = 250L; 
ptlPosn.y = 100L; 

GpiLine( hps 

/* -PS handle 


*/ 

, &ptlPosn 
); 

/* -coordinate 

position 

*/ 

ptlPosn.x = 150L; 
ptlPosn.y = 200 L; 

GpiLine( hps 

/* -PS handle 


*/ 

, &ptlPosn 
); 

/* -coordinate 

position 

*/ 

ptlPosn.x = 50L; 
ptlPosn.y = 100L; 

GpiLine( hps 

/* -PS handle 


*/ 

, &ptlPosn 
); 

/* -coordinate 

position 

*/ 

ptlPosn.x = 50L; 
ptlPosn.y = 5 0 L; 

GpiMove( hps 

/* -PS handle 


*/ 

, &ptlPosn 
); 

/* -coordinate 

position 

*/ 

ptlPosn.x = 250L; 
ptlPosn.y = 50L; 

GpiLine( hps 

/* -PS handle 


*/ 

, &ptlPosn 

/* -coordinate 

position 

*/ 


); 


return; 

} 


Figure 1.7 (continued) 
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/* 


drawa rea, 

. c */ 

VOID DrawArea(HPS hps) 

/ 




i 

/* Reset the PS, erase the window, set 

the 

AREABUNDLE (area bundle) 

*/ 

/* attributes and draw an area. 



*/ 

/* 



*/ 

/* inputs: hps PS handle 



*/ 

/* 



*/ 

POINTL ptlPosn ; 

/* 

coordinate position 

*/ 

POINTL ptlPatRef ; 

/* 

pattern origin 

*/ 

/* 

t ~k ~k i 


< -k-k -k ! 

*/ 

/* Reset the PS and erase the window. 



*/ 

/* 

****■) 


*/ 
z-k-k -k J 

GpiResetPS( hps 

/* 

-PS handle 

*1 

, GRES_ALL 

/* 

-options 

*1 

J 9 

GpiErase!hps ); 

/* 

-PS handle 

*/ 

/* 

1 


r -k-k-k j 

*/ 

/* Set the AREABUNDLE attributes. 



*/ 

/* 

k-***-J 

c *******************************^ 

*/ 
ir*** / 

GpiSetColor! hps 

/* 

-PS handle 

*/ 

, CLR_BLUE 

'i . 

/* 

-foreground color 

*/ 

J 9 

/* 

set background color (ignored 

*/ 


/* 

with background mix BM_LEAVEALONE)*/ 

GpiSetBackColor( hps 

/* 

-PS handle 

*/ 

, CLR_YELLOW 

\ • 

/* 

-background color 

*/ 

J f 

/* 

-set foreground mix 

*/ 

GpiSetMix! hps 

/* 

-PS handle 

*/ 

, FM_OVERPAINT 

/* 

-foreground mix mode 

*/ 

j , 

/* 

set background mix 

*/ 

GpiSetBackMix( hps 

/* 

-PS handle 

*/ 

, BM_OVERPAINT 

/* 

-background mix mode 

*/ 

J , 

/* 

set pattern set 

*/ 

GpiSetPatternSet ( hps 

/* 

-PS handle 

*/ 

, LCID_DEFAULT 

/* 

-pattern set 

*/ 

j , 

/* 

set pattern symbol 

*/ 

GpiSetPattern ( hps 

/* 

-PS handle 

*/ 

, PATSYM DIAG1 
); 

/* 

-pattern symbol 

*/ 

ptlPatRef . x = OL; 




ptlPatRef.y = OL; 

/* 

set pattern origin 

*/ 

GpiSetPatternRefPoint ( hps 

/* 

-PS handle 

*/ 

, &ptlPatRef 

/* 

-pattern reference point 

*/ 


); 


Figure 1.8 DrawArea Function. 
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/* 

/* 

/* 


ptlPosn.x = 50L; 
ptlPosn.y = 100L; 


GpiMove( hps 

/* -PS handle 

*/ 

, &ptlPosn 
); 

/* -coordinate position 

*/ 

GpiBeginArea( hps 

/* -PS handle 

*/ 

, (BA NOBOUNDARY 
j BA ALTERNATE) 

) ; 

/* options 

*/ 

ptlPosn.x = 250L; 
ptlPosn.y = 100L; 

GpiLine( hps 

/* -PS handle 

*/ 

, &ptlPosn 
); 

/* -coordinate position 

*/ 

ptlPosn.x = 150L; 
ptlPosn.y = 200L; 

GpiLine( hps 

/* -PS handle 

*/ 

, &ptlPosn 
); 

/* -coordinate position 

*/ 

ptlPosn.x = SOL; 
ptlPosn.y = 100 L; 

G piLin e( hps 

/* -PS handle 

*/ 

, &pt1Posn 

/* -coordinate position 

*/ 


); 


Draw an area. 


GpiEndArea(hps ) ; 
r e t u r n ; 


Figure 1.8 (continued) 



30 OS/2 PRESENTATION MANAGER GPl 

/* drawmark.c */ 

VOID DrawMarkers(HPS hps) 

{ 

/* Reset the PS, Erase the window, set the MARKERBUNDLE (marker bundle) */ 

/* attributes and draw some markers. */ 

/* */ 

/* inputs: hps PS handle */ 

/* */ 

POINTL ptlPosn ; /* coordinate position */ 

SIZEF sizfxMkrBox ; /* marker box size */ 

/* */ 

/* Reset the PS and erase the window. */ 

/* */ 

GpiResetPSC hps /* -PS handle */ 

, GRES_ALL /* -options */ 

); 

GpiErase(hps); /* -PS handle */ 

/* */ 

/* Set the MARKERBUNDLE attributes. */ 

/* */ 

/* set foreground color */ 

GpiSetColor( hps /* -PS handle */ 

, CLR_BLUE /* -foreground color */ 

); 

/* set background color (ignored */ 
/* with background mix BM_LEAVEAL0NE)*/ 
GpiSetBackColor( hps /* -PS handle */ 

, CLR_YELL0W /* -background color */ 

); 

/* -set foreground mix */ 

GpiSetMix( hps /* -PS handle */ 

, FM_0VERPAINT /* -foreground mix mode */ 

); 

/* set background mix (normally */ 

/* BM_LEAVEAL0NE for simple markers) */ 
GpiSetBackMix( hps /* -PS handle */ 

, BM_OVERPAINT /* -background mix mode */ 

); 

/* set marker set */ 

GpiSetMarkerSet( hps /* -PS handle */ 

, LCID_DEFAULT /* -marker set */ 

); 

/* set marker symbol */ 

GpiSetMarker( hps /* -PS handle */ 

, MARKSYM_CR0SS /* -character mode */ 

); 

sizfxMkrBox.cx = MAKEFIXED(50,0); /* set marker box (ignored for base */ 

sizfxMkrBox.cy = MAKEFIXED(50,0); /* marker set and raster font markers*/ 

GpiSetMarkerBox( hps /* -PS handle */ 

, &sizfxMkrBox /* -marker box (50 x 50) */ 

); 


Figure 1.9 DrawMarkers Function. 
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/* */ 

/* Draw some markers. */ 

/* */ 

ptlPosn.x = 50L; 

ptlPosn.y = 100L; 

GpiMarker( hps /* -PS handle */ 

, &ptlPosn /* -coordinate position */ 

); 

ptlPosn.x = 70L; 

ptlPosn.y = 110 L; 

GpiMarker( hps /* -PS handle */ 

, &ptlPosn /* -coordinate position */ 

); 

ptlPosn.x = 90L; 

ptlPosn.y = 120L; 

GpiMarkerC hps /* -PS handle */ 

, &ptlPosn /* -coordinate position */ 

); 

ptlPosn.x = 110 L; 

ptlPosn .y = 105 L; 

GpiMarker( hps /* -PS handle */ 

, &ptlPosn /* -coordinate position */ 

); 

ptlPosn.x = 130L; 

ptlPosn.y = 95L; 

GpiMarker( hps /* -PS handle */ 

, &ptlPosn /* -coordinate position */ 

); 

return; 

} 


Figure 1.9 (continued) 
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/* wcbitblt.c */ 


VOID WCBitBlt(HPS hps, USHORT usBitmapId) 

{ 

/* Reset the PS, erase the window, set the IMAGEBUNDLE (image bundle) */ 

/* attributes and BitBlt to the display. */ 

/* */ 

/* inputs: hps PS handle */ 

/* */ 


^define XTARGET 50L 
^define YTARGET 40L 


HBITMAP hbm 

POINTL aptlCoords[4] 

POINTL ptlBmapSize 

BITMAPINFOHEADER bmpData 


/* bitmap handle */ 
/* target/source coordinate array */ 
/* bitmap size */ 
/* BITMAPINFOHEADER structure */ 



hbm = GpiLoadBitmap( hps 

, (HMODULE)NULL 
, usBitmapId 
, OL 
, OL 
); 


/* 


*/ 


/* Reset the PS and erase the window. 
/* 


*/ 

*/ 


GpiResetPSC hps 

/* -PS handle 

*/ 

, GRES_ALL 

/* -options 

*/ 

) , 

GpiErase(hps); 

/* -PS handle 

*/ 


/* 

/* Set the IMAGEBUNDLE attributes. 
/* 


*/ 

*/ 

*/ 


Figure 1.10 WCBitBlt Function. 
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GpiSetColor( hps /* -PS handle */ 

, CLR_BLUE /* -foreground color */ 

); 

/* set background color (ignored */ 

/* with background mix BM_LEAVEALONE)*/ 

GpiSetBackColor( hps /* -PS handle */ 

, CLR_YELLOW /* -background color */ 

); 

/* -set foreground mix */ 

GpiSetMix( hps /* -PS handle */ 

, FM_OVERPAINT /* -foreground mix mode */ 

); 

/* set background mix */ 

GpiSetBackMixC hps /* -PS handle */ 

, BM_OVERPAINT /* -background mix mode */ 

); 

/********* ****************************************************** *************** j 
/* */ 

/* Query the bitmap dimensions, convert to device coordinates (by */ 

/* subtracting 1), convert to world coordinates and BitBlt to the window. */ 

/* */ 

/********★*******★*****★*****★★★******★★******★*★★★***********★***★★**■*■*★★•*■★■*••*■•*•/ 

GpiQueryBitmapParameters( hbm /* -bitmap handle */ 

, &bmpData /* -BITMAPINFOHEADER structure */ 

); 

ptlBmapSize.x = bmpData.cx - 1; 
ptlBmapSize.y = bmpData.cy - 1; 

GpiConvert( hps /* -PS handle */ 

, CVTC_DEVICE /* -source */ 

, CVTC_WORLD /* -target */ 

, 1L /* -count */ 

, &ptlBmapSize /* -coordinate array */ 


); 

aptlCoords[0].x = XTARGET; 

aptlCoords[0].y = YTARGET; 

aptlCoords[1].x = XTARGET + ptlBmapSize.x; 

aptlCoords[1].y = YTARGET + ptlBmapSize.y; 

aptlCoords[2].x = OL; 

aptlCoords[2].y = OL; 

aptlCoords[3].x = bmpData.cx; 

aptlCoords[3].y = bmpData.cy; 


GpiWCBitB1t( hps /* -PS handle */ 

, hbm /* -bitmap handle */ 

, 4L /* -number of coordinate points */ 

, aptlCoords /* -coordinate points */ 

, R0P_SRCC0PY /* -rop mix value */ 

, BB0_0R /* -options */ 

); 



Gpi DeleteBitmap(hbm); 
return; 


Figure 1.10 (continued) 
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/* 


rotate. c 

*/ 

VOID Rotate(HPS hps) 

; 




i 

/* Erase the window, and rotate a figure 

with its bottom left origin 

*/ 

/* located at (100,150) 30.0 degrees counterclockwise about this point 

*/ 

/* (using the model transform matrix). 



*/ 

/* 



*/ 

/* inputs: hps PS handle 



*/ 

/* 



*/ 

P0INTL ptlPosn 

/* 

coordinate position 

*/ 

MATRIXLF matlfModel ; 

/* 

model transform matrix 

*/ 

/* 

ir ******-* 


k-k j 

*/ 

/* Erase the window. 



*/ 

/* 

********* 

r **************************** : 

*/ 

k *J 

GpiErase(hps ) ; 

/* 

-PS handle 

*/ 

/* 

k****-k*-> 


k*j 

*/ 

/* Construct and set the model transform 

matrix 

to provide the required 

*/ 

/* rotation. 



*/ 

/* 

^-k'k'k'k'k'k-) 

f ****************************, 

*7 

**/ 

ptlPosn.x = 100L; 




ptlPosn.y - 150L; 




GpiRotate( hps 

/* 

-PS handle 

*/ 

, &matlfModel 

l* 

-transform matrix 

*/ 

, TRANSFORM REPLACE 

/* 

-options 

*/ 

, MAKEFIXED(30,0) 

/* 

-angle of rotation 30.0 deg. 

*/ 

, &ptlPosn 
); 

/* 

-center of rotation 

*/ 

GpiSetModelTransformMatrix( hps 

/* 

-PS handle 

*/ 

, 9 L 

/* 

-number of matrix elements 

*/ 

, &matlfModel 

/* 

-transform matrix 

*/ 

, TRANSF0RM_ADD /* 

-options 

*/ 


); 


/* 

/* Draw the figure. 
/* 

/ ★★★★★★ ■A:^ 


Figurel.il Rotate Function. 
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ptlPosn.x = 100L; 

ptlPosn.y = 150 L; 

GpiMove( hps /* -PS handle */ 

, &pt1Posn /* -coordinate position */ 

); 

ptlPosn.x = 150L; 

ptlPosn.y = 200L; 

GpiLine( hps /* -PS handle */ 

, &ptlPosn /* -coordinate position */ 

); 

ptlPosn.x = 100L; 

ptlPosn .y = 200L; 

GpiLine( hps /* -PS handle */ 

, &ptlPosn /* -coordinate position */ 

); 

ptlPosn.x = 150L; 

ptlPosn.y = 150L; 

GpiLine( hps /* -PS handle */ 

, &ptlPosn /* -coordinate position */ 

); 


return; 

} 


Figure 1.11 (continued) 


/* seale.c */ 


VOID Seale(HPS hps) 

{ 

/* Erase the window, and scale a figure with its bottom left origin */ 

/* located at (100,150) by a factor of 2.0 in both x and y directions */ 

/* (using the model transform matrix). */ 

/* */ 

/* inputs: hps PS handle */ 

/* */ 

P0INTL ptlPosn ; /* coordinate position */ 

MATRIXLF matlfModel ; /* model transform matrix */ 

FIXED afxScale[2] ; /* x y scale factors */ 

/★**★★★★★★★★★★********★*★*******★***★*★**************•*■*■*:★*★★★★★★■*•■*:*★★**★ ******* / 

/* */ 

/* Erase the window. */ 

/* */ 

/*★***★*★***★*★********★*★★***★***********★****★*★★****★***★*★★•*•*★*★**•*:★•*•*★***★ / 

GpiErase(hps ); /* -PS handle */ 

/★*★★★*★*★★★***★*★*********************************★**★★****★**★★**★*■★★★*★*★★★*/ 
/* */ 

/* Construct and set the model transform matrix to provide the required */ 

/* scaling. */ 

/* */ 




Figure 1.12 Scale Function. 
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afxScale[0] = MAKEFIXED(2,0) ; 

/* x scaling = 2.0 

*/' 

afxScale[1] = MAKEFIX ED(2,0); 

/* y sealing = 2.0 

*/ 

ptlPosn.x = 100L; 



ptlPosn.y = 150L; 



GpiScale( hps 

/* -PS handle 

*/ 

, &matlfModel 

/* -transform matrix 

*/ 

, TRANSF0RM_REPLACE 

/* -options 

*/ 

, afxScale 

/* -x and y scale factors 

*/ 

, &ptlPosn 
); 

/* -center of sealing 

*/ 

GpiSetModelTransformMatrix( hps 

/* -PS handle 

*/ 

, 9L 

/* -number of matrix elements 

*/ 

, &matlfModel 

/* -transform matrix 

*/ 

, TRANSFORM ADD 
) ; 

/* -options 

*/ 

/* 


*■** / 
*1 

/* Draw the figure. 


*1 

/* 

t *******************************, 

*/ 
k-k* j 

ptlPosn.x = 100L; 



ptlPosn.y = 150L; 



GpiMove( hps 

/* -PS handle 

*1 

, &ptlPosn 
); 

/* -coordinate position 

*/ 

ptlPosn.x = 150L; 



ptlPosn .y = 200L; 



GpiLine( hps 

/* -PS handle 

*/ 

, &ptlPosn 
); 

/* -coordinate position 

*/ 

ptlPosn.x = 100L; 



ptlPosn.y = 200L; 



GpiLine( hps 

/* -PS handle 

*/ 

, &ptlPosn 
); 

/* -coordinate position 

*/ 

ptlPosn.x = 150L; 



ptlPosn.y = 150L; 



GpiLine( hps 

/* -PS handle 

*/ 

, &ptlPosn 

/* -coordinate position 

*/ 


); 


return ; 

} 


Figure 1.12 (continued) 
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/* translat.c */ 

VOID Translate(HPS hps) 

{ 


/* Erase 

the window, 

and translate the 

picture by (50,100) 

*/ 

/* (using 

the model transform matrix). 


*/ 

/* 




*/ 

/* inputs 

: hps 

PS handle 


*/ 

/* 




*/ 

POINTL 

ptlPosn 


/* coordinate position 

*/ 

MATRIXLF 

matlfModel 

; 

/* model transform matrix 

*/ 



GpiErase(hps ); /* -PS handle */ 


/* 


*/ 


/* Construct and set the model transform matrix to provide the required 
/* translation. 

/* 


*/ 

*/ 

*/ 


ptlPosn.x = 50L; 
ptlPosn.y = 10 0 L ; 


GpiTranslate( hps 

/* 

-PS handle 

*/ 

, &matlfModel 

/* 

-transform matrix 

*/ 

, TRANSF0RM_REPLACE 

/* 

-options 

*/ 

, &ptlPosn 
); 

/* 

-translation coordinates 

*/ 

GpiSetModelTransformMatrix( hps 

/* 

-PS handle 

*/ 

, 9 L 

/* 

-number of matrix elements 

*/ 

, &matlfModel 

/* 

-transform matrix 

*/ 

, TRANSF0RM_ADD 

/* 

-options 

*/ 


/* 

*/ 

/* Draw the figure. 

*/ 

/* 

*/ 


Figure 1.13 Translate Function. 
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ptlPosn.x = 100 L; 

pt1Posn.y = 150L; 

GpiMove( hps 

, &ptlPosn 

); 

ptlPosn.x = 150L; 

ptlPosn.y = 200L; 

GpiLine( hps 

, &pt1Posn 

); 

ptlPosn.x = 100L; 

ptlPosn.y = 200L; 

GpiLineC hps 

, &ptlPosn 

); 

ptlPosn.x = 150 L; 

ptlPosn.y = 150 L; 

GpiLine( hps 

, &ptlPosn 

); 

return; 

} 

Figure 1.13 


/* -PS handle */ 

/* -coordinate position */ 


/* -PS handle */ 

/* -coordinate position */ 


/* -PS handle */ 

/* -coordinate position */ 


/* -PS handle */ 

/* -coordinate position */ 


(continued) 
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/* dsppmerr.c */ 

VOID DisplayPMError(HAB hab, PSZ pszString) 

{ 

/* display: PM Error / Severity / Base OS/2 RC / PM Error Message */ 

/* */ 

/* PM Error is a hex error code defined in pmerr.h */ 

/* */ 

/* Severity is hex number and is one of: 0 (SEVERITY_NOERROR) */ 

/* 4 (SEVERITY_WARNING) */' 

/* 8 (SEVERITY_ERROR) */ 

/* C (S EV E RITY_S EV E R E) */ 

/* 10 (SEVERITYJJNRECOVERABLE) */ 

/* */ 

/* Base OS/2 RC is a decimal error number defined in bseerr.h */ 

/* */ 

/* PM Error Message is a null terminated text string describing the PM Error. */ 
/* */ 

/* The pszString input parameter is available for use by the caller, for */ 

/* example, to identify the name of the PM call that failed. */ 

/* */ 


CHAR achOutput[80] ; /* 
LONG errid ; /* 
SHORT s0S2Rc =0 ; /* 
PSHORT psOS2Rc ; /* 
PSZ pszErrMsg = ; /* 
PSHORT psOffset ; /* 
PERRINFO perrilnfo = NULL ; /* 


/* get last error 

errid = WinGetLastError(hab); 


message string CHAR array */ 
error id */ 
base (OS/2) return code */ 
base (OS/2) return code pointer */ 
PM error message pointer */ 
pointer offset */ 
ERRINFO pointer */ 


*/ 


/* if last error not ’ok' display error message box 


*/ 


if (ERRORIDERR0R(errid) != PMERR_0K) 

{ 


/* get error info */ 

perrilnfo = WinGetErrorlnfo(hab); 

/* get PM error message pointer */ 

psOffset = MAKEP(SELECT0R0F(perriInfo), (perriInfo->offaoffszMsg 
+ 0FFSET0F(perriInfo))); 
pszErrMsg = MAKEP(SELECT0R0F(perriInfo), 

(*ps0ffset + 0FFSET0F(perriInfo))); 

/* if error code is PMERR_BASE_ERROR get base OS/2 error code */ 

if (ERRORIDERR0R(errid) == PMERR_BASE_ERROR) 

{ 

ps0S2Rc = MAKEP(SELECT0R0F(perriInfo), (perriInfo->offBinaryData 
+ 0FFSET0F(perriInfo))); 
s0S2Rc = *ps0S2Rc ; 

} 


Figure 1.14 DisplayPMError Function. 
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/* format the message string 



*/ 

sprintf(achOutput,"%x/%x/%d/%s %s\n M , 




ERRORIDERROR(errid), 

/* 

PM error code 

*/ 

ERRORIDSEV(errid) , 

/* 

severity 

*/ 

sOS2Rc, 

/* 

base OS/2 error number 

*/ 

pszErrMsg, 

/* 

PM error message 

*/ 

pszString); 

/* 

callers string 

*/ 

/* display the error 



*/ 

WinMessageBox( HWND DESKTOP 

/* 

parent window 

*/ 

, NULL 

/* 

owner window 

*/ 

, achOutput 

/* 

message text 

*/ 

, “Error/Severity/0S2RC/ErrMsg” 

/* 

message box title 

*/ 

, 1 

/* 

message box id 

*/ 

, MB CUACRITICAL 

/* 

window style 

*/ 

j MB SYSTEMMODAL 




MB_OK 





); 


/* free the error info */ 

if (perriInfo) 

WinFreeErrorlnfo(perrilnfo); 
return; 

} 


Figure 1.14 (continued) 




Presentation Spaces and Device Contexts 


In order to perform any GPI Drawing operation to an output device, a device 
context or DC is required for the device. This must be linked to, or associated with, 
a presentation space or PS. 


DETOE CONTEXTS 

A DC represents the particular instance of a shared output device to which the 
drawing from an application is directed. A printer, for example, would be shared 
by all applications wishing to produce printed output and each application would 
create its own printer DC to which its output would be directed. In the case of a 
display, different applications, or different parts of the same application, would 
require their output to be directed at different windows on the screen. To accom¬ 
plish this, each would open a DC for its own particular target window and direct 
its output at this (window) DC. 

A DC can be regarded as a logical output device consisting of a block of memory 
containing device state information relating to a particular job. This includes such 
things as window origin, picture orientation, current drawing color, current x,y 
position and so forth. DCs fall into the following groups: 

Display Window DCs 

Display window DCs are created explicitly or, if already created previously, 
queried using: 

WinOpenWindowDC; and 

WinQueryWindowDC. 
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Display window DCs are also implicitly allocated along with a presentation space 
(see below) by: 

WinGetPS; 

WinGetClipPS; 

WinGetScreenPS; and 

WinBeginPaint. 

All display DCs are window DCs and the window must first be created to enable 
its handle to be passed as a parameter to these functions. Display DCs are the only 
DCs not created using DevOpenDC. 

Queued DCs 

Queued DCs are used for printing and plotting queued output via the spooler and 
are created using DevOpenDC with a DC-type parameter of OD_QUEUED. 

Direct DCs 

Direct DCs are used for printing and plotting directly to a device (bypassing the 
spooler) and are used by the system to print queued print jobs as they are 
dequeued from the print queue. Direct DCs should not normally be used by 
applications as, unlike queued DCs, they do not enable an output device to be 
properly shared between different applications. Direct DCs are created using 
DevOpenDC with a DC-type parameter of OD_DIRECT. 

Info DCs 

Info DCs can be created for any device and have all the characteristics of a normal 
DC but produce no output to the device. They have a smaller memory overhead 
than a normal DC and exist solely for querying device information (e.g., device 
capabilities, device fonts, printer forms, character positioning information). Info 
DCs are created using DevOpenDC with a DC-type parameter of ODJNFO. 


MetaFile DCs 

MetaFile DCs are used to record drawing primitives and resources (fonts, color 
tables, etc.) in a MetaFile for interchange purposes. When the MetaFile DC is 
closed, a memory MetaFile is established and its handle returned to the applica¬ 
tion. The memory MetaFile can then be drawn, passed to other applications via 
the clipboard, or saved in application memory or as a file for interchange. MetaFile 
DCs are created using DevOpenDC with a DC-type parameter of OD_METAFILE 
or OD_METAFILE_NOQUERY. These two types are the same except that the 
latter provides better recording performance at the expense of not allowing 
drawing attribute values to be queried. 
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Memory DCs 

Memory DCs are required for bitmap operations. A bitmap is selected into a 
Memory DC in order to draw to it or use it as the target or source of BitBlt 
operations. Memory DCs are created using DevOpenDC with a DC-type parame¬ 
ter of OD_MEMORY. 

See Appendix 1 for a full description of DevOpenDC parameters. 

PRESENTATION SPACES 

In order to output to a device, an application requires a presentation space or PS 
associated with the target DC. The purpose of the PS is to retain device indepen¬ 
dent data (in addition to that retained by the DC) and resources between applica¬ 
tion calls. The application will store the PS handle and, once the PS and DC are 
associated, the PS will store the (associated) DC handle. The DC in turn holds a 
handle to an extension of the DC known as the Device Drawing Context (DDC) 
which is owned by the Presentation Driver (in the early days of Driver Interface 
definition this DDC handle or hddc was referred to as the'Magic Cookie’). This is 
illustrated for both a Normal-PS and Micro-PS in Figures 2-1 and 2-2. There are 
three different types of PS: 

Micro-PS 

Applications, for which a DC alone can retain all the necessary information still 
require a PS for consistency but a simple PS, called a Micro-PS, will suffice. A 
Micro-PS is permanently associated with its DC and the PS part of this PS/DC pair 
effectively contains only handles of the associated DC and PS resources. A Micro- 
PS therefore minimizes the amount of memory required and is fast to create. It 
does, however, offer significantly less function than a Normal-PS. A Micro-PS 
should be used in preference to a Normal-PS whenever possible. 

Normal-PS 

A Normal-PS supports all GPI functions. Unlike a Micro-PS, it can be disassoci¬ 
ated from one DC and associated with another. For example, an application 
drawing to a window might wish to disassociate the PS from the window DC and 
associate it with a printer or MetaFile DC in order to print the picture or record it 
in a MetaFile. A Normal-PS should only be used for applications that require 
functions not supported by a Micro-PS. 

Cached Micro-PS 

A variation of the Micro-PS is the cached Micro-PS. An application that creates a 
large number of windows, and permanently allocates a DC for each, will rapidly 
deplete the total number of available DCs for the process. This is resolved by use 
of a cached Micro-PS that is intended for use with windows requiring a PS and DC, 
but requiring no information to be retained (other than that visible on the display) 
between each sequence of output operations. 
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GPI GRE DDI 



Figure 2.1 Normal—PS and DC Data Objects. 


A cached Micro-PS is really a PS/DC pair. Unlike a Normal-PS or uncached 
Micro-PS, the DC part of this PS/DC pair is allocated with the PS from a cache and 
does not need to be explicitly created. Otherwise a cached Micro-PS is very similar 
to an uncached Micro-PS. It can be rapidly allocated (and reinitialized) and 
deallocated and does not need to be permanently tied to a particular window. As 
soon as one sequence of output operations is complete, it should be returned to the 
cache (i.e., before the relevant Window Procedure completes), making it available 
for use with other windows. A cached Micro-PS may only be used with display 
windows, whereas an uncached Micro-PS can be used with any output device. A 
cached Micro-PS should be used by applications that need a large number of 
windows and require the same PS and DC to be shared by different windows. 

PS CREATION AND ASSOCIATION 

A Normal-PS or (uncached) Micro-PS is created and optionally associated using: 
GpiCreatePS 

A full description of the GpiCreatePS parameters is provided later in this chapter. 
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Figure 2.2 Micro—PS and DC Data Objects. 


ANormal-PS can be associated with a DC and, by specifying a NULL, DC handle, 
disassociated using: 

GpiAssoeiate 

As mentioned earlier, a cached Micro-PS/DC pair is obtained using: 

WinGetPS; 

WinGetClipPS; 

WinGetScreenPS; and 
WinBeginPaint. 

WinGetClipPS is similar to WinGetPS but provides additional clipping. 
WinReleasePS must be used with WinGetPS/WinGetClipPS/WinGetScreenPS in 
order to return the PS/DC pair to the cache. WinBeginPaint and WinGetScreenPS 
are both for specialized use as described below. 

WinBeginPaint is provided for responding to WM_PAINT messages to ensure 
that the relevant parts of a window are correctly repainted when ‘healing’ is 
required (for example, when an overlaying window is removed). Note that when 
an existing PS is available, its handle should be passed to WinBeginPaint as a 
parameter rather than requesting the system to allocate a new cached Micro-PS. 
Otherwise, a cached Micro-PS can be requested by specifying the PS handle 
parameter as NULL prompting WinBeginPaint to allocate a cached Micro-PS and 
return its handle. WinEndPaint must follow WinBeginPaint to signal completion 
of WM_PAINT processing and to return any cached PS/DC pair to the cache. 
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WinGetScreenPS will return a cached PS/DC pair for the Desk Top window (i.e., 
the entire display screen). This function might be used, for example, by an 
application wishing to capture the entire screen in a bitmap for printing. This 
function makes it possible for an application to write over any part of the display 
screen, including windows owned by other applications, and should, therefore, 
only be used with extreme caution. Otherwise, use of WinGetScreenPS is the same 
as for WinGetPS. 


GPISETPS 


Although the PS page size, page units, and long/short coordinate format specified 
on GpiCreatePS will often remain unchanged for the life of the PS, they can be 
modified together with an optional PS reset using GpiSetPS. However, certain 
restrictions apply to the use of this function. In particular, it should not be used 
for a PS associated with a DC of type OD_QUEUED with data type PM_Q_STD 
(see chapter 12), or with a DC of type OD_METAFILE or OD_METAFILE_NOQU- 
ERY (see chapter 11). 

SUMMARY OF PS AND DO CREATION AND ASSOCIATION 

Display Window DC 

This is created using WinOpenWindowDC and destroyed with the window by 
WinDestroyWindow. Once opened it can be subsequently queried using 
WinQuery WindowDC, 

Non-Display Window DC 

This is created and destroyed using DevOpenDC and DevCloseDC. 

Normal-PS or uncached Micro-PS 

These are created and destroyed using GpiCreatePS and GpiDestroyPS. 

Association of DC and a Normal-PS or an uncached Micro-PS 

This is performed using GpiAssociate (for a Normal-PS only) or GpiCreatePS with 
the GPIA_ASSOC option. Disassociation of a Normal-PS and DC is performed 
using GpiAssociate with a NULL DC handle. A Micro-PS cannot be disassociated 
from its DC except by destroying the PS. 

Allocation/De-Allocation of cached Micro-PS/DC pair for a window 

This is performed using WinGetPS/WinGetClipPS and WinReleasePS. 

Allocation/De-Allocation of cached Micro-PS/DC for WM_PAINT processing 

This is performed using WinBeginPaint and WinEndPaint with the 
WinBeginPaint PS handle parameter specified as NULL. 
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Use of an existing PS and associated window DC for WM_PAINT processing 

This is performed using WinBeginPaint and WinEndPaint with the 
WinBeginPaint PS handle parameter specified as the handle of the existing PS. 

Allocation and De-Aliocation of cached Micro-PS/DC pair for the desktop 

This is performed using WinGetScreenPS and WinReleasePS. 

A selection of these operations are illustrated by the Functions in Figures 2-3 to 
2-7. 


GPICREATEPS PARAMETERS 

The GpiCreatePS parameters are as follows: 

HPS GpiCreatePS ( HAB hab 
, HDC hdc 
, PSIZEL psizlPS 
, ULONG flOptions 
); 


hab 

This is the anchor block handle returned by Winlnitialize. 

hdc 

If the GPIA_ASSOC option is specified, this is the handle of the DC with which 
the newly created PS is to be associated. If GPIA_NOASSOC is specified this can 
be specified as NULL. 

psizlPS 

This specifies the size of the PS page in page units. The maximum permissible 
value for either dimension is 0x07FFFFFF (or 134217727). If GPIA ASSOC is 
specified, either or both dimensions may be specified as zero causing them to be 
defaulted to a size determined by the associated device output area. If this is a 
display window then the defaults are determined by the the screen dimensions. If 
the page units are PU_ARBITRARY and only one dimension is defaulted, its value 
is set to that which ensures that the picture aspect ratio is preserved. Where both 
dimensions are defaulted, the default values are determined by the device pel 
dimensions. The actual values of the PS page dimensions are only important in 
certain cases as follows: 
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1. If PU_ARBITRARY page units are specified then the PS page dimen¬ 
sions represent the drawing limits that will be visible on the output 
media. 

2. If GpiSetPageViewport is to be issued then the PS page dimensions 
together with the new page viewport will determine the new device 
transform matrix and page units. 

3. If the PS is to be used to record a MetaFile then the PS page dimen¬ 
sions will be recorded in the MetaFile as the picture dimensions. These 
dimensions might be used when the MetaFile is redisplayed. 

4. If the ARE= 5 and ‘FIT=’ print queue processor parameters are used to 
scale to fit or specify the position or size of the output area during 
printing, then any picture scaling and so forth, will be performed using 
the PS page dimensions. 

It is recommended that very small PS page dimensions (e.g., 2x2) should not be 
used. Ideally, the dimensions should either be defaulted or reflect the size of the 
preferred output media (maximized display window, printer form size, etc.). See 
chapter 7 for a more complete description of PS page size. 

flOptions 

This specifies a combination of the following: 

PS_UNITS specifies page units as one of: 

PU_ARBITRARY; 

PUJPELS; 

PUJLOMETRIC; 

PUHIMETRIC; 

PUJLOENGLISH; 

PUHIENGLISH; and 

PUTWIPS. 

See chapter 7 for a description of page units. 

PS_FORMAT specifies the long or short retained segment and MetaFile world 
coordinate format as one of: 

GPIFJLONG (coordinate range is 0xF8Q00000-0x07FFFFFF); 

GPIF_SHORT (coordinate range is 0xFFFF80(X)-A)x0(XX)7FFF); and 

GPIFJDEFAULT (= GPIFJLONG). 

This option controls the size of coordinates stored in the drawing orders of 
retained graphics segments and MetaFiles and is ignored for non-retained graph¬ 
ics output. Coordinates stored in GPIF_SHORT format require less memory but it 
is the responsibility of the application to ensure that truncation of 32 bit primitive 
coordinates to 16 bit order coordinates does not result in loss of data (for example, 
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a large positive value greater than 32767 could appear negative after truncation). 
For performance reasons this checking is not performed by the system. 

PS_TYPE specifies the type of PS (i.e., Micro-PS or Normal-PS) as one of: 

GPIT_MICRO; and 

GPIT_NORMAL. 

PS_ASSOC specifies association or no association as one of: 

GPIA_ASSOC (mandatory for GPIT_MICRO); and 
GPIA_NOASSOC. 

PS_MODE (the mode option) is not used. 

Return Value 

The handle of the newly created PS is returned or, if an error was detected, the 
error is logged and a NULL PS handle (i.e., GPI_ERROR) is returned. 

PS AND DC CONTROL AND QUERY FUNCTIONS 

A number of useful PS control and query functions are provided, several of which 
are used in the examples throughout this book. 

DevEscape 

DevEscape is provided to enable data to be sent directly to or received directly from 
a Presentation (device) Driver, bypassing the GPI. Escape codes may be unique to 
a particular driver but a number of predefined codes exist. The most commonly 
used are DEVESC_STARTDOC, DEVESC_ENDDOC, DEVESC_ABORTDOC, 
DEVESC_NEWFRAME and DEVESC_RAWDATA, which are used for printing. 
DEVESC_STARTDOC and DEVESC_ENDDOC are in fact mandatory for print 
jobs and DEVESCJRAWDATA is used to pass raw data (e.g., ASCII text for most 
printers) to a Presentation Driver. When a DevEscape function is issued to a 
MetaFile or PM_Q_STD/OD_QUEUED DC, depending on the escape code value, 
the function is either processed immediately by the driver or recorded in the 
MetaFile or print file. The action taken for the different escape code ranges is as 
follows: 

0—8149 processed immediately for all DC types. 

8150-16299 recorded in MetaFile and processed 

immediately for OD_QUEUED DC. 

16300—24449 recorded in both MetaFile and print file. 

24450-32599 recorded in print file and processed 
immediately for MetaFile DC. 


32600-32767 


reserved. 
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32768-40959 

40960-49151 

49152-57343 

57344-65535 


processed immediately for all DC types. 

recorded in MetaFile and processed 
immediately for OD_QUEUED DC. 

recorded in both MetaFile and print file. 

recorded in print file and processed 
immediately for MetaFile DC. 


Use of DevEscape is illustrated by a number of the examples in this book. 


DevQueryCaps 

DevQueryCaps enables the device characteristics (e.g., resolution) to be deter¬ 
mined for a particular device. 

GpiErase 

GpiErase is intended primarily for use with displays to erase the window to 
background color. 

GpiQueryDevice 

GpiQueryDevice is a useful function that returns the handle of the DC associated 
with a specified PS. Certain PM functions (e.g., DevEscape) require a DC handle 
as a parameter and this function avoids the need to include the DC handle as 
parameter to application functions in addition to the PS handle. 


GpiResetPS 

GpiResetPS resets the presentation space. Three levels of reset are available: 

GRES_ATTRS resets the picture drawing attributes to default. 

GRES_SEGMENTS, in addition to performing a GRES_ATTRS 
reset operation, destroys all retained graphics segments and resets 
all PS environment attributes (e.g., default viewing transform, de¬ 
fault drawing attributes) to their initial value. Logical font and color 
table resources are preserved. 

GRES_ALL performs a full presentation space reset destroying all 
resources (i.e., logical fonts and color tables) in addition to perform¬ 
ing GRES_ATTRS and GRES_SEGMENTS reset operations. 


GpiSavePS/GpiRestorePS 

These are fairly coarse save and restore functions included mainly for compatibil¬ 
ity. As they save and restore a combination of both picture and environment 
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information they do not fit tidily into the picture and environment’ model de¬ 
scribed in chapter 1. For this reason, they cannot be used with retained graphics 
segments and, if used for recording a MetaFile, will produce a MetaFile that does 
not correctly conform to the interchange architecture. 


/* 




nmpsdraw.c */ 

BOOL NormalPSDrawCHWND hwnd, PDEVOPENDATA pdopData) 

/ 


/* 

Use a Normal-PS to draw to a display window followed 

by a printer as */ 

/* 

fol1ows: 



*/ 

/* 




*/ 

/* 

Query the anchor block handle. 



*/ 

/* 

Obtain a window DC handle for the window. 



*/ 

/* 

Create a Normal-PS and associate with the 

window 

DC. 

*/ 

/* 

Draw to the PS. 



*/ 

/* 

Dissociate the PS from the window DC. 



*/ 

/* 

Create an 0D_QUEUED DC for the printer. 



*/ 

/* 

Associate the PS and the printer DC. 



*/ 

/* 

Issue ’start document’ DevEscape required 

by the 

printer. 

*/ 

/* 

Draw to the PS. 

*/ 

/* 

Issue ’end document’ DevEscape. 



*/ 

/* 

Dissociate the PS from the printer DC. 



*/ 

/* 

Destroy the PS. 



*/ 

/* 

Close the printer DC. 



*/ 

/* 



*/ 


Figure 2.3 NormalPSDraw Function. 
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/* inputs: hwnd 

Window handle 


*/ 

/* pdopData 

Complete DEVOPENSTRUC 

structure for the target printer 

*/ 

/* 

(see PrintDefPrinter) 


*/ 

/* 




*/ 

^define CHSTRW 

“window text” 



^define NCHRSW 

(LONG)(sizeof(CHSTRW)-1) 


^define CHSTRP 

“printer 

text” 



^define NCHRSP 

(LONGMsizeof(CHSTRP)-l) 


^define PDOCNAME 

“Print Job” 



^define PDOCNAMELEN (LONG)sizeof(PDOCNAME) 


HAB hab 



/* anchor block handle 

*/ 

HDC hdcWnd = NULL 


/* display window DC handle 

*/ 

HPS hps = GPI ERROR 


/* PS handle 

*/ 

BOOL fRet = FALSE 


/* BOOL return code 

*/ 

HDC hdcPrt = DEV ERROR 


/* printer DC handle 

*/ 

BOOL fRetA = FALSE 


/* BOOL GpiAssociate return code 

*/ 

LONG 1 Length 



/* ENDDOC returned data length 

*/ 

USHORT usJobld 



/* ENDDOC returned job id 

*/ 

SIZEL sizlPS 



/* PS page size 

*/ 

POINTL ptlCoord 



/* coordinate point 

*/ 




/* obtain the anchor block handle 

*/ 

hab = WinQueryAnchorBlock(hwnd); 

/* -window handle 

*/ 

if(hab!=NULL) 



/* obtain a DC for the window 

*/ 

hdcWnd = WinQueryWindowDC(hwnd); 

/* -window handle 

*/ 

if (hdcWnd==NULL) 





hdcWnd = WinOpenWindowDC(hwnd); 

/* -window handle 

*/ 

sizlPS.cx=0 L; 



/* set PS dimensions = zero 

*/ 

sizlPS.cy=0L; 



/* (i . e. default) 

*/ 

if (hdcWnd!=NULL) 



/* create PS and associate 

*/ 

hps = GpiCreatePS( 

hab 


/* -anchor block handle 

*7 


hdcWnd 


/* -DC handle 

*/ 


&sizlPS 


/* -presentation page size 

*/ 


P U_P E LS 


/* -options 

*/ 


GPIF DEFAULT 




GPIT NORMAL 




GPIA_ASSOC 

; 



ptlCoord.x = 100L; 





ptlCoord.y = 100L; 





if (hps!=GPI_ERR0R) 



/* draw to PS 

*/ 

fRet = (BOOL)GpiCharStringAt( hps 

/* -PS handle 

*/ 



, &ptlCoord 

/* -coordinate point 

*/ 



, NCHRSW 

/* -number of characters 

*/ 



, CHSTRW 
) ; 

/* -character string 

*/ 

if (hps!=GPI_ERR0R) 



/* dissociate PS & window DC 

*/ 

fRet = GpiAssociate( hps 


/* -PS handle 

*/ 


, NULL 


/* -DC handle (= NULL) 

*/ 


) && fRet; 


Figure 2.3 (continued) 
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if (fRet) /* create printer DC */ 

hdcPrt = DevOpenDC( hab /* -anchor block handle */ 

, 0D_QUEUED /* -DC type */ 

, /* -token */ 

, 9L /* -count of pdopData elements */ 

, pdopData /* -Open DC data */ 

, NULL /* -compatible hdc (n/a) */ 

); 

if (hdcPrtI=DEV_ERR0R) /* associate PS and printer DC */ 

fRet = (fRetA = GpiAssociate( hps /* -PS handle */ 

, hdcPrt /* -DC handle */ 

)); 

if (fRet) /* issue ’start document’ DevEscape */ 

fRet = DevEscape( hdcPrt /* -DC handle */ 

, DEVESC_STARTDOC /* -escape code */ 

, PDOCNAMELEN /* -size of document name */ 

, PDOCNAME /* -null terminated document name */ 

, NULL /* -size of output data (not used)*/ 

, NULL /* -output data (not used) */ 

) == DEV_0K; 

ptlCoord.x = 100L; 

ptlCoord.y = 100L; 

if (fRet) /* draw to PS */ 

fRet = (BOOL)GpiCharStringAt( hps /* -PS handle */ 

, &ptlCoord /* -coordinate point */ 

, NCHRSP /* -number of characters */ 

, CHSTRP /* -character string */ 

): 

1 Length = 2L; 

if(fRet) /* issue ’end document’ DevEscape */ 

fRet = DevEscape( hdcPrt /* -DC handle */ 

, DEVESC_ENDDOC /* -escape code */ 

» OL /* -length of input data (OL) */ 

, NULL /* -input data (not used) */ 

, &1Length /* -size of output data (2L) */ 

, (PBYTE)&usJobId /* -output data (returned job id) */ 

) == DEV_0K; 

if (fRetA) /* dissociate PS and printer DC */ 

fRet = GpiAssociate( hps /* -PS handle */ 

, NULL /* -DC handle (= NULL) */ 

) && fRet; 

if (hps!=GPI_ERROR) /* destroy PS */ 

fRet = GpiDestroyPS(hps) && fRet; /* -PS handle */ 

if (hdcPrt!=DEV_ERR0R) /* destroy printer DC */ 

fRet = DevCloseDC( hdcPrt /* -DC handle */ 

) != DEV_ERR0R && fRet; 


return(fRet); 


Figure 2.3 (continued) 





54 


OS/2 PRESENTATION MANAGER GPl 


/* upswdraw.c */ 

BOOL MicroPSWindowDraw(HWND hwnd) 


/* Use a non cached Micro-PS to draw to a display window as follows: */ 
/* */ 
/* Query the anchor block handle. */ 
/* Obtain a window DC handle for the window. */ 
/* Create a Micro-PS and associate with the window DC. */ 
/* Draw to the PS. */ 
/* Destroy the PS. */ 
/* */ 
/* inputs: hwnd Window handle */ 
/* */ 


//define CHSTRMW “window text" 

//define NCHRSMW ( LONG)(si zeof (CHSTRMW)-1) 


HDC hdcWnd = NULL ; 

/* 

window DC handle 


*/ 

HPS hps = GPI ERROR ; 

/* 

PS handle 


*/ 

BOOL fRet = FALSE ; 

/* 

BOOL return code 


*/ 

SIZEL sizlPS ; 

/* 

PS page size 


*/ 

POINTL ptlCoord ; 

/* 

coordinate point 


*/ 


/* 

obtain the anchor block handle 

*/ 

hab = WinQueryAnchorBlock(hwnd); 

/* 

-window handle 


*/ 

if(hab!=NULL) 

/* 

obtain a DC for the 

window 

*/ 

hdcWnd = WinQueryWindowDC(hwnd); 

/* 

-window handle 


*/ 

if (hdcWnd==NULL) 





hdcWnd = WinOpenWindowDC(hwnd); 

/* 

-window handle 


*/ 

sizlPS.cx=0L; 

/* 

set PS dimensions = 

zero 

*/ 

sizlPS.cy=0L; 

/* 

(i . e. default) 


*/ 

if (hdcWnd!=NULL) 

/* 

create Micro-PS and 

associate 

*/ 

hps = GpiCreatePS( hab 

/* 

-anchor block handle 


*/ 

, hdcWnd 

/* 

-DC handle 


*/ 

, &siz1 PS 

/* 

-presentation page size 

*/ 

, PU_PELS 

/* 

-options 


*/ 


GPIF_DEFAULT 


j GPIT_MICRO 
I GPIA_ASS0C 
); 


ptlCoord.x = 100L; 
ptlCoord.y = 100L; 
if (hpsI=GPI_ERROR) 


/* 

draw to PS 

*/ 

fRet = (BOODGpi CharStri ngAt( 

hps 

/* 

-PS handle 

*/ 

, 

&ptlCoord 

/* 

-coordinate point 

*/ 

, 

NCHRSMW 

/* 

-number of characters 

*/ 

) 

CHSTRMW 

/* 

-character string 

*/ 

if (hps!=GPI_ERR0R) 


/* 

destroy the Micro-PS 

*/ 

fRet = GpiDestroyPSChps) && 

fRet; 

/* 

-PS handle 

*/ 


return(fRet); 

} 


Figure 2.4 MicroPSWindowDraw Function. 
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/* upsndraw.c */ 

BOOL MicroPSNonDisplayDraw(HAB hab, PDEVOPENDATA pdopData) 

{ 

/* Using a non-cached Micro PS, draw to a non-display printer device as */ 

/* fol1ows: */ 

/* */ 

/* Obtain a DC for the printer. */ 

/* Create a Micro-PS and associate with the printer DC. */ 

/* Issue ’start document’ DevEscape required by the printer. */ 

/* Draw to the PS. */ 

/* Issue ’end document’ DevEscape. */ 

/* Dissociate the PS from the printer DC. */ 

/* Destroy the PS. */ 

/* Close the printer DC. */ 

/* */ 

/* inputs: hwnd Window handle */ 

/* pdopData Complete DEVOPENSTRUC structure for the target printer */ 

/* (see PrintDefPrinter) */ 

/* */ 


//define CHSTRN “printer text” 

//define NCHRSN ( LONG) ( si zeof( CHSTRN )-1) 

//define NDDOCNAME "Print Job” 

//define NDDOCNAMELEN ( LONG) si zeof (NDDOCNAME) 


HDC 

hdcPrt 

HPS 

hps = GPI ERROR 

BOOL 

fRet = FALSE 

POINTL 

ptlCoord 

SIZEL 

s i z 1 P S 

LONG 

1 Length 

USHORT 

usJobld 

hdcPrt 

= DevOpenDC( hab 


, 0D_QUEUED 
9 L 

, pdopData 
, NULL 
); 

sizlPS.cx = sizlPS.cy = OL; 
if (hdcPrt != DEV_ERR0R) 
hps = GpiCreatePS( hab 

, hdcPrt 
, &sizlPS 
, PU_PELS 
GPI F_DEFAU LT 
GPIT_MICRO 
GPIA_ASS0C 

) ; 

if (hps!=GPI_ERR0R) 

fRet = DevEscapeC hdcPrt 

, DEVESC_STARTDOC 
, NDDOCNAMELEN 
, NDDOCNAME 
, NULL 
, NULL 

) == DEV_0K; 


/* printer DC handle */ 
/* PS handle */ 
/* BOOL return code */ 
/* coordinate point */ 
/* PS page size */ 
/* length of returned job id */ 
/* returned print job id */ 

/* open non-window DC */ 
/* -anchor block handle */ 
/* -DC type */ 
/* -token */ 
/* -count of pdopData elements */ 
/* -Open DC data */ 
/* -compatible hdc (n/a) */ 

/* create Micro PS and associate */ 
/* -anchor block handle */ 
/* -DC handle */ 
/* -PS page size */ 
/* -options */ 


/* issue ’start document’ DevEscape */ 


/* -DC handle */ 
/* -escape code */ 
/* -size of document name */ 
/* -null terminated document name */ 
/* -size of output data (not used)*/ 
/* -output data (not used) */ 


Figure 2.5 MicroPSNonDisplayDraw Function. 
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ptlCoord.x = 100L; 
ptlCoord.y = 100L; 


if (fRet) 



/* 

draw to PS 


*/ 

fRet = 

(BOOL)GpiCharStringAt( 

hps 

/* 

-PS handle 


*/ 


, 

&ptlCoord 

/* 

-coordinate point 


*/ 


, 

NCHRSN 

/* 

-number of characters 


*/ 


) 

CHSTRN 

/* 

-character string 


*/ 

1 Length = 

2 L; 






if(fRet) 



/* 

issue ’end document’ DevEscape 

*/ 

fRet = 

DevEscape( hdcPrt 


/* 

-DC handle 


*/ 


. DEVESC_ENDDOC 

/* 

-escape code 


*/ 


, OL 


/* 

-length of input data 

(OL) 

*/ 


, NULL 


/* 

-input data (not used) 


*/ 


, &1Length 


/* 

-size of output data (2L) 

*/ 


, (PBYTE)&usJobId 

/* 

-output data (returned 

job id) 

*/ 


) == DEV_0K; 





if (hps ! 

= GPI_ERR0R) 


/* 

destroy the PS 


*/ 

fRet = 

GpiDestroyPS(hps) && 

fRet; 

/* 

-PS handle 


*/ 

if (hdcPrt != DEV_ERR0R) 


/* 

close the DC 


*/ 

fRet = 

DevCloseDC( hdcPrt 


/* 

-DC handle 


*/ 


) != DEV_ERR0R && fRet; 


return(fRet); 

} 


Figure 2.5 (continued) 
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/* 

BOOL CachedMicroPSWindowDraw(HWND hwnd) 

/* Use a Cached Micro-PS to draw to a display window as follows 
/* 

/* Get cached Micro-PS/DC pair. 

/* Draw to the window. 

/* Release the cached PS/DC pair 

/* 

/* inputs: hwnd Window handle 
/* 


//define CHSTRC “window text” 

//define NCHRSC ( LONG) (si zeof( CHSTRC)-1) 


HPS 

hps ; 

/* PS handle 

*/ 

BOOL 

fRet = FALSE ; 

/* BOOL return code 

*/ 

POINTL 

ptlCoord ; 

/* coordinate point 

*/ 



/* get cached PS/DC pair 

*/ 

hps = 

Wi nGetPS(hwnd); 

/* -window handle 

*/ 


ptlCoord.x = 100L; 
ptlCoord.y = 100L; 
if (hps!=NU LL) 

fRet = (BOOL)GpiCharStringAt( hps 

, &ptlCoord 
, NCHRSC 
, CHSTRC 
) ; 

if (hps!=NULL) /* release cached PS/DC pair */ 

fRet = WinReleasePS(hps) && fRet; /* -PS handle */ 

return(fRet); 


Figure 2.6 CachedMicroPSWindowDraw Function. 


/* draw to PS */ 
/* -PS handle */ 
/* -coordinate point */ 
/* -number of characters */ 
/* -character string */ 


cachdraw.c */ 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 
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' pwmpaint.c */ 

BOOL ProcessWmPaint(HWND hwnd, HPS hps) 

{ 

/* Perform WM_PAINT processing. If hps is NULL a cached Micro-PS is allocated */ 
/* and used for the paint. If hps is the handle of an existing PS already */ 
/* associated with a DC for the window then this existing PS is used for the */ 
/* paint. */ 

//define CHSTRR “repaint window text” 

//define NCHRSR ( LONG) (sizeof (CHSTRR)-1) 


HPS hpsPaint ; 


/* 

PS handle 

*/ 

RECTL rclRect ; 


/* 

rectangle 

*/ 

BOOL fRet = FALSE ; 


/* 

BOOL return code 

*/ 

POINTL ptlCoord ; 


/* 

coordinate point 

*/ 



/* 

begin paint 

*/ 

hpsPaint = WinBeginPaint( hwnd 


/* 

-window handle 

*/ 

, hps 


/* 

-ps handle (may be NULL) 

*/ 

, &rclRect 
); 

/* 

-returned bounding rectangle 

*/ 

if (hpsPaint != NULL) 


/* 

repaint window 

*/ 

fRet = WinFillRect( hpsPaint 


/* 

-PS handle 

*/ 

, &rclRect 


/* 

-rectangle requiring repaint 

*/ 

, CLR_BACKGROUND 
. 

/* 

-fill color 

*/ 

j , 

ptlCoord.x = 100L; 





ptlCoord.y = 100L; 





if (fRet) 


/* 

draw to PS 

*/ 

fRet = (BOOL)GpiCharStringAt( 

hpsPaint 

/* 

-PS handle 

*/ 

, 

&ptlCoord 

/* 

-coordinate point 

*/ 

, 

NCHRSR 

/* 

-number of characters 

*/ 

) 

CHSTRR 

/* 

-character string 

*/ 

if (hpsPaint != NULL) 


/* 

end paint 

*/ 

fRet = WinEndPaint(hpsPaint) 

&& fRet; 

/* 

-PS handle 

*/ 


return(fRet); 


} 

Figure 2.7 ProcessWmPaint Function. 





Drawing Primitives and Attributes 


ATTRIBUTES 


Chapter 1 described how graphics drawing is accomplished using drawing attri¬ 
bute functions (e.g., GpiSetColor GpiSetMix), and drawing primitives (e.g., GpiL- 
ine, GpiCharStringAt), where the drawing attribute functions control the drawing 
attributes (e.g., color, mix) to be used and the drawing primitives specify the 
output operation to be performed. It was also pointed out that the drawing 
primitives and their attributes can be divided into five major groups.. In the case 
of attributes, these groups are called attribute bundles. Certain other non-bundle 
attributes also exist. 

Most attributes may be set to default or an explicit non-default value. The 
attribute value used for drawing is then taken from one of two places, either the 
default, or the normal bundle structure. 

Bundle Attributes 

Bundle attributes are those attributes that apply to a particular primitive type 
according to the following five groups: 

Characters and Text (CHARBUNDLE); 

Lines and Curves (LINEBUNDLE); 

Filled Areas or Patterns (AREABUNDLE); 

Markers (MARKERBUNDLE); and 

Image and BitBlt pixel operations (IMAGEBUNBLE). 
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Any combination of attributes for a particular bundle can be set to a specified or 
default value and queried using: 

GpiSetAttrs; and 

GpiQueryAttrs. 

For GpiSetAttrs, separate default and attribute mask parameters define which 
attributes are modified and which of these are to be set to default value. For 
GpiQueryAttrs, a mask parameter defines the attributes to be queried and a 
returned value identifies which of these are currently set to default. 

In addition, the color and mix attributes, which appear in multiple bundles, are 
called global attributes. These can be set or queried for an individual bundle using 
GpiSetAttrs/GpiQueryAttrs as described above or can be set for all applicable 
bundles simultaneously using: 

GpiSetColor; 

GpiSetMix; 

GpiSetBackColor (not applicable to LINEBUNDLE); and 

GpiSetBackMix (not applicable to LINEBUNDLE). 

The corresponding query functions return values from the CHARBUNDLE and 
are: 


GpiQueryColor; 

GpiQueryMix; 

GpiQueryBackColor; and 
GpiQueryBackMix. 

Functions also exist to set and query each of the non-global bundle attributes 
individually as listed below. These are really for convenience and provide no 
additional function over and above GpiSetAttrs/GpiQueryAttrs. For the 
LINEBUNDLE these are: 

GpiSetLineWidth/GpiQueryLineWidth; 

GpiSetLineWidthGeom/GpiQueryLineWidthGeom; 

S etLineTypq/Gp iQuery LineTyp e; 

GpiSetLineEnd/GpiQueryLineEnd; and 

Gpi S etLineJ o in/GpiQueryLineJ oin. 

For the CHARBUNDLE these are: 

GpiSetCharSei/GpiQueryCharSet; 

GpiSetCharModq/GpiQueryCharMode (i.e., precision); 

GpiSetCharBo^GpiQueryCharBox (i.e., cell); 
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GpiSetCharAnglq/GpiQueryChar Angle; 

GpiSetCharShear/GpiQueryCharShear; and 

GpiSetCharDirection/GpiQueryCharDirection. 

For the AREABUNDLE these are: 

GpiSetPattemSel/GpiQueryPattemSet; 

GpiSetPatterxyGpiQueryPattern (i.e., symbol); and 

GpiSetPattemRefPoini/GpiQueryPatternRefPoint. 

For the MARKERBUNDLE these are: 

GpiSetMarkerSei/GpiQueryMarkerSet; 

GpiSetMarker/GpiQueryMarker (i.e., symbol); and 

GpiSetMarkerBox/GpiQueryMarkerBox (i.e., cell). 

All IMAGEBUNDLE attributes are global attributes and so the IMAGEBUNDLE 
has no additional functions. 

Note that although the TineWidthGeom' LINEBUNDLE attribute is fully sup¬ 
ported, currently (for IBM OS/2 Version 1.3 at least), the ‘LineWidth/ attribute has 
not been implemented for any device and can only be set to its initial default value 
of 1.0. 

The bundle attributes are described in detail with their corresponding drawing 
primitive descriptions below. 

ion-Bundl© Attributes 

In addition to the bundle attributes described above, the following non-bundle 
attributes exist: 

Current Position; 

Arc Parameters; 

Viewing Limits; 

Primitive Tag; 

Model Transform Matrix; and 
Viewing Transform Matrix. 

The set and query functions for these are: 

GpiMovq/GpiSetCurrentPosition/GpiQueryCurrentPosition; 

GpiSetArcParam^/GpiQueryArcParams; 

Gp i S et Vie wingLimit^/Gp i Query V ie wingLimits; 
GpiSetTag/GpiQueryTag; 
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GpiSetModelTransformMatriVGpiQueryModelTransformMatrix; and 

GpiSetViewingTransforirLlVIatriVGpiQueryViewingTransformMatrix. 

The model transform matrix drawing attribute is also updated by the segment 
transform matrix when the segment is drawn, or by the GpiCallSegmentMatrix 
instance transform when the segment call is executed (see chapter 7). 

The viewing transform matrix attribute, unlike other attributes, is unique in 
that it applies only to graphics segments (including non-retained segments). To 
understand its use, it is necessary to distinguish between the different forms of 
viewing transform matrix that may exist. These are held in the: 

presentation space; 

retained segments; and 

drawing attributes. 

Only the latter is a true drawing attribute. 

The matrix held in the presentation space is set and queried using the 
GpiSetViewingTransformMatrix and GpiQueryViewingTransformMatrix func¬ 
tions mentioned above. This matrix is not used directly as a drawing attribute, but 
when GpiOpenSegment is issued to open a graphics segment, it is used to con¬ 
struct the segment viewing transform matrix for the new segment. This sets the 
drawing attribute directly for the duration of the segment definition and drawing, 
is stored in an internal prolog at the start of the new retained segment, or both, 
depending on drawing mode (DM_DRAW, DM_RETAIN or DMJDRAWANDRE- 
TAIN). A viewing transform matrix stored in the internal prolog of a retained 
segment is used to set the drawing attribute for the duration of the segment 
whenever it is subsequently drawn (e.g., using GpiDrawChain). Viewing trans¬ 
form operation is illustrated in Figure 3—1. 

When using GpiOpenSegment to create a new unchained segment that is to be 
a called (rather than a root) segment, the presentation space viewing transform 
matrix value should first be reset to identity (see chapter 7). 

Currently IBM OS/2 Version 1.3 provides no means of querying the viewing 
transform matrix value of either a retained segment or the drawing attributes. 
This significantly affects the usefulness of this function. 

Attribute Mode and Attribute Popping 

A Normal-PS contains a LIFO stack that holds the return information for called 
segments. This stack also allows the existing value of any of the above attributes 
(except viewing limits and viewing transform matrix) to be automatically pushed 
as a new value is set and restored later using GpiPop. This attribute pushing 
occurs if the attribute mode is set to AM_PRESERVE. Note that 
GpiSetCurrentPosition allows the current position to be pushed whereas 
GpiMove, which is otherwise identical, does not. The default (reset) value of 
attribute mode is AM_NOPRESERVE. Attribute mode is set and queried using: 
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RETAINED 

SEGMENT 



DRAWING 

ATTRIBUTES 


^Drawing attribute viewing transfers matrix is reset at the 
end, of each root segment for retained segment drawing and 
by GpiCloseSegment (for modes DM_DRAW/DM_DRAWANDRETAIN). 

Figure 3.1 Viewing Transform Matrix Operation. 


GpiSetAttrMode; and 
GpiQueryAttrMode. 

Attributes are restored (or popped) in the reverse order from which they were 
pushed. GpiPop includes a count parameter specifying the number of attributes to 
be popped. For attributes pushed (and set) using a single global attribute setting 
function (e.g., GpiSetColor), a count of one is sufficient to pop the global attribute 
for all bundles. If, however, multiple attributes are pushed (and set) using a single 
GpiSetAttrs call, a count of more than one is required to pop all the attributes. 
Alternatively, the attributes may be popped by using GpiPop multiple times with 
a smaller count. In this case the attributes are popped in the order in which they 
appear in their attribute bundle (i.e., color attribute first). 

Unpopped attributes in a chained (root) segment are automatically popped and 
discarded at the end the segment during any of the GpiDraw or GpiCorrelate 
functions. Unpopped attributes in a called segment are automatically popped and 
restored on return to the caller. 

Default Attributes 

The above primitive attribute setting functions allow all attributes to be set to either 
a specified or default value. The default values are initialized to defined constant 
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values, certain of which are device dependent, or can be set to application defined 
values. The initial default values are listed in the IBM OS/2 Programming Guide, 
Default attributes are set to application defined values and queried using: 

GpiSetDefAttrs/GpiQueryDefAttrs; 

GpiSetDefArcParamVGpiQueryDefArcParams; 

GpiSetDefTag/GpiQueryDefTag; and 

GpiSetDefViewingLimits/GpiQueryDefViewingLimits. 

Unlike the other attribute setting functions described in this chapter, default 
attributes are PS environment attributes and, therefore, should not be varied 
during drawing, 

Attribute Querying 

Functions described earlier enable any drawing attribute value (except viewing 
transform matrix) to be queried. It is, however, invalid to attempt to query drawing 
attributes under either of the following conditions: 

1. When a PS is associated with a DC of type OD_METAFILE_NOQU- 
ERY. 

2. When an open segment is being updated or edited without being 
drawn (i.e., actual drawing mode is RETAIN). 

Drawing attributes can be queried but are in an undefined state after any of the 
following operations: 

GpiDrawSegment; 

GpiDrawFrom; 

GpiDrawChain; 

GpiCorrelateSegment; 

GpiCorrelateFrom; 

GpiCorrelateChain; 

GpiCallSegment; 

GpiOpenSegment (if ATTRJFASTCHAIN = ATTR_OFF for the 
segment); and 

GpiCloseSegment. 


Attribute Resetting 

Drawing attributes are reset to default value by any of the following: 

• Any 'set attribute' function specifying default value (e.g., GpiSetMix 
FM_DEFAULT). 
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• GpiSetAttrs with a flag set in both the attributes and defaults mask. 

• GpiResetPS. 

® GpiSetPS (with PS_NORESET option not specified). 

• GpiPlayMetaFile (with RES_RESET option specified). 

• GpiAssociate. 

• GpiOpenSegment (in mode DM_DRAW or DM_BRAWANDRETAIN 
if ATTR_FASTCHAIN = ATTR_OFF). 

• At the start of any root segment during any of the following opera¬ 
tions if ATTR_FASTCHAIN = ATTR_OFF for the segment: 

GpiCorrelateChain; 

GpiCorrelateFrom; 

GpiCorrelateSegment; 

GpiDrawChain; 

GpiDrawFrom; and 

GpiDrawSegment. 

Default drawing attributes are reset to their initial default value by: 

• GpiSetDefAttrs with a flag set in both Attributes and Defaults Mask. 

• GpiResetPS (option: GRES_SEGMENTS or GRES_ALL). 

® GpiSetPS (with PS_NORESET option not specified). 

® GpiPlayMetaFile (with RES_RESET option specified). 


TEXT AUB CHARACTER FUNCTIONS 
Character Huddle Attributes 

Characters are drawn using the CHARBUNDLE (character bundle) attributes. 
The CHARBUNDLE attributes and flags (parenthesized) are as follows: 


ICoior (CBB.COLOR) 

This specifies the character color. 


IBackColor (CBB_BACK_COLOR) 

This specifies the character box (or cell) background color. 


usMixMode (CBBJ/IIXJ/IODE) 

This specifies the character mix mode. 



66 


OS/2 PRESENTATION MANAGER GPl 


usBackMixMode (CBB_BACK_MiX_MODE) 

This specifies the character box (or cell) background mix mode. 

usSet (CBB__SET) 

This defines the id of the font to be used for drawing characters. A value of zero 
(LCIDDEFAULT) specified with GpiSetCharSet sets the current character set to 
default. A value of zero specified with GpiSetAttrs or GpiSetDefAttrs sets the 
current or default character set back to the initial default set. 

usPrecssion (CBB_MODE) 

This defines the character mode or precision with which characters should be 
drawn in terms of which character bundle attributes must be honored, which are 
optional, and whether or not the font must be an outline font. This is specified as 
one of: 


CM_MODE 1 specifies that character box, angle, shear, and direc¬ 
tion attributes may be ignored for raster font characters. All other 
character attributes are fully honored. CM_MODEl raster charac¬ 
ters are always drawn as normal left to right text. 

CM_MODE2 specifies that character box, angle, shear, and direc¬ 
tion attributes are used to determine the position of each raster font 
character only. Orientation and size are unaffected by these attri¬ 
butes and all other character attributes are fully honored. 

CM_MODE3 specifies that characters must be drawn using an 
outline font. Raster font characters are invalid in this mode. For out¬ 
line characters, all attributes are fully honored regardless of mode. 

sizfxCelS (CBB_BOX) 

This defines the character box or cell width and height in world coordinates. These 
dimensions control the size of outline font characters (regardless of mode) and the 
spacing of outline and CM_MODE2 raster font characters. For outline characters, 
the IFmlnc and lEmHeight font metrics are set to the character box dimensions 
with other width and height metrics (e.g., lAveCharWidth and IMaxBaselineExt) 
scaled in the same proportion. The ratio CharacterWidtb/lEmlnc is normally 
constant for a given character of a particular font or, for a non-proportional font, 
for all characters of the font (i.e., lAveCharWidth/lEmlnc). The horizontal charac¬ 
ter spacing of outline and CM_MODE2 raster characters can therefore be deter¬ 
mined by CharacterBox.cx*CharacterWidth/lEmInc. 

One or both character box dimensions can be specified as zero causing outline 
characters to collapse into line or a single point. 

Character box dimensions may also be negative causing outline characters to be 
drawn reflected and the character spacing of both outline and CM_MODE2 raster 
characters to be reversed. 

For ideally proportioned (i.e., as designed) outline characters, the character box 
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width/height ratio should match the metrics ratio sXDeviceRe^/sYDeviceRes. This 
is normally one for outline fonts as these are generally defined in a 1000x1000 
square space. An exception is a device outline font such as a plotter font. 

For outline font characters, the two rectangles sX/YDeviceRes and character box 
define a transform from font definition space to world coordinates. This extra 
transform sits above the model transform matrix illustrated in Figure 7-2. 

Note that even when drawing using the default font and character mode 
CMJMODEl, unless the application has verified that the font really is a raster font, 
it is still necessary to set the character box attribute. It must be set to a value in world 
coordinates that will produce correctly sized outline characters for the current 
transforms. This is essential to ensure that the application will operate successfully 
with any current and future devices that provide an outline font as their default. Note 
also that an outline font may be returned from GpiCreateLogFont due to a raster font 
match failure. This will also require that the character box attribute be set correctly. 

Examples of the character box attribute are illustrated in Figure 3-2. 

ptIAngle (CBB_ANGLE) 

This defines the character angle as the coordinates of a point that specifies the 
angle of the baseline of a character string. For CM_MOBEl raster characters, 
character angle is ignored. For CM__MODE2 raster characters, character angle 
affects only the position of each character but not its orientation. For CM_MODE3, 
the current font must be an outline font. For outline characters in all modes, 
character angle affects both position and orientation of characters. Characters are 
drawn perpendicular to the rotated baseline. A character angle value of (0,0) is 
interpreted as ‘set to default.' The initial default value of character angle is (1,0) 
representing a character angle of zero that positions characters left to right along 
the x axis. Examples of the character angle attribute are illustrated in Figure 3—3. 
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Figure 3.2 Character Box Attribute (positive and negative values). 
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Figure 3.3 Character Angle Attribute. 


ptIShear (CBB_SH£AR) 

This defines the character shear as the coordinates of a point that specifies a shear 
angle. A non-zero shear angle gives the character an oblique or italicized appear¬ 
ance. A character shear value of (0,0) is interpreted as 'set to default/ The initial 
default value of character shear is (0,1) giving upright characters. If the values are 
both positive or both negative, the tops of the characters slope to the right. If the 
signs are opposite, they slope to the left. An example of character shear is 
illustrated in Figure 3—4. 


Shear 

Angle 


\'ulline Font 


Figure 3.4 Character Shear Attribute. 
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usDirection (CBB_DIRECTION) 

This specifies the character direction as one of: 

CHDIRN_LEFTRIGHT (left to right); 
CHDIRN_TOPBOTTOM (top to bottom); 
CHDIRNJRIGHTLEFT (right to left); 
CHDIRN_BOTTOMTOP (bottom to top); 

Examples of the character direction attribute are illustrated in Figure 3—5. 
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Figure 3.5 Character Direction Attribute. 
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Character String Primitives 

Character strings can be drawn using any of the following functions: 

GpiCharString; 

GpiCharStringAt; 

GpiCharStringPos; or 

GpiCharStringPosAt. 

GpiCharString and GpiCharStringAt are identical except the latter draws from a 
specified point rather than the current position. Likewise, GpiCharStringPos and 
GpiCharStringPosAt are identical except GpiCharStringPosAt draws from a spec¬ 
ified point rather than the current position. 

GpiCharStringPos and GpiCharStringPosAt offer the following additional op¬ 
tions over and above GpiCharString and GpiCharStringAt: 

CHS_OPAQUE specifies that the rectangle parameter defines a 
background rectangle that should be filled using character back¬ 
ground color and overpaint mix attributes. 

CHS_VECTOR specifies that the increment vector parameter 
should be used to define the character spacing in world coordinates. 
This can be used by an application to precisely control the position¬ 
ing of each individual character. For example, it can be used to pro¬ 
vide kerning or to draw proportional font characters with fixed pitch. 

CHS_LEAVEPOS specifies that the current position should not be 
updated by this function. Otherwise, the function (like GpiCharStr- 
ing/GpiChar String At) will update the current position to the posi¬ 
tion at the end of the string where the next character would be 
drawn. 

CHS_CLIP specifies that the rectangle parameter provided should 
be used for clipping the characters output by this function. 

Additional functions are provided to process the character string in an identical 
manner to GpiCharStringPos and GpiCharStringPosAt but, instead of drawing 
the characters, return the coordinate positions at which each character would be 
drawn. These are: 

GpiQueryCharStringPos; and 

GpiQueryCharStringPosAt. 

C8iar m Extra and BreakJExtra Spacing 

Some devices (e.g., PostScript™) allow the spacing between each character to be 
increased by an additional amount specified in world coordinates using 
DevEscapq/DEVESC_CHAR_EXTRA. This char_extra spacing is in addition to 
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any width vector (provided with GpiCharStringPos) and any kerning adjustment. 
The char_extra spacing is initialized to zero when a DC is created. 

Such devices also allow the width of each break (or space) character to be 
increased by an additional amount specified in world coordinates using 
DevEscap^DEVESC_BREAK_EXTRA. The break_extra spacing is in addition to 
the char_extra spacing. The break_extra spacing is initialized to zero when a DC 
is created. 

The codepoint of the space or break character of a font is returned by 
GpiQueryFonts as one of the metrics. 


LINE AND CURVE FUNCTIONS 
Line Bundle Attributes 

Lines and arcs are drawn using the LINEBUNDLE (line bundle) attributes. In the 
case of arcs (GpiPointArc, GpiPartialArc, and GpiFullArc), the ARC PA RAMS (arc 
parameters) are also used. In addition, the AREABUNDLE (area bundle) attri¬ 
butes are used when either of the fill options are specified with GpiFullArc or 
GpiBox. The LINEBUNDLE attributes and flags (parenthesized) are as follows: 


IColor (LBB__CO10R) 

This specifies the line color. 


usMixMode (LBB_MIX_MODE) 

This specifies the line mix mode. 


fxWidth (LBB_WIDTH) 

This specifies the cosmetic line width as a multiplier consisting of an integer and 
fractional part. As a minimum, if the cosmetic line width is greater than 1.0, this 
should produce double width lines; otherwise, the lines should be single width. In 
practice, however, values other than 1.0 are unsupported by IBM OS/2 Version 1.3. 
Cosmetic line width is of type FIXED (see chapter 1). 


SGeomWidth (LBB_GEOM_WIDTH) 

This specifies the geometric line width. This is used exclusively with paths (see 
below). 


usType (LBB_TYPE) 

This specifies the line style, for example, solid, dotted, (see Figure 3-6). 
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-- UNFrYFEjxnr 

- mETYPE.SHORTDASH 

- UNETYPE_J)ASHDOT 

-- -- -- -- -- - UNETYPEJX)UBLEDOT 

-UNETYPEJLONGDASH 

- UNETYPEJ3ASHSX)UBLEEK)T 

- LENETYPE_SOLID 

- UNETYPE^ALTERNATE 

UNETYPEJNVISIBLE 
Figure 3.6 Standard Line Types. 


usEnd (IBBJEND) 

This specifies the line end attribute. This is used exclusively with paths (see 
below). 

usJoin (LBB_J0IN) 

This specifies the line join attribute. This is used exclusively with paths (see 
below). 

Line and tom Primitive Functions 

The line and curve primitive functions are described below. 

Gpiline 

This draws a single straight line from the current position to a specified point and 
updates the current position. 

GpiPolyline 

This draws a succession of connected straight lines from the current position through 
a series of specified points. The current position is updated to the last point in the 
series. Points may be coincident and the number of specified points can be zero, in 
which case the function is a no-op. This function is a superset of that of GpiLine. 
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GpiPolyFillet 

This draws a succession of fillets starting from the current position and ending at 
the last in a series of specified points. The fillets pass through the mid-point of the 
second and all subsequent imaginary straight lines up to and including, the last 
but one of a series connecting the current position and all adjacent specified points. 
The fillets are tangential to the imaginary lines at the current position, the last 
point in the series, and all mid-points through which they pass. If only two points, 
including current position, are specified, then the curve is tangential at the current 
position and second point. The current position is updated to the last point in the 
series. Points may be coincident and the number of specified points can be zero, in 
which case the function is a no-op. Examples of the two cases of GpiPolyFillet are 
illustrated in Figure 3—7. 

GpiPolyFiiletSharp 

This draws a succession of fillets starting from the current position, passing 
through alternate points and ending at the last of a series of 2*n specified points 
(where n is the number of fillets). The fillets are tangential to imaginary straight 
lines connecting adjacent points at each point through which they pass. The 
alternate points through which fillets do not pass are control points used with a 
sharpness value from a sharpness array supplied as a separate parameter. The 
current position is updated to the last point in the series. Points may be coincident 
and the number of specified points can be zero, in which case the function is a 
no-op. GpiPolyFiiletSharp is illustrated in Figure 3-7. 

Each sharpness value is a ratio controlling the sharpness of one fillet (see Figure 
3—8) where: 

sharpness >1.0 defines a hyperbola; 

sharpness - 1.0 defines a parabola; and 

sharpness <1.0 defines an ellipse. 


GpiPolySpline 

This draws a succession of Bezier splines starting from the current position and 
passing through every third point of a series of 3*n specified points (where n is the 
number of splines). The pairs of intervening points are control points. The current 
position is updated to the last point in the series. Points may be coincident and the 
number of specified points can be zero, in which case the function is a no-op. 
GpiPolySpline is illustrated in Figure 3-7. 

GpiFullArc 

This draws a complete circular or elliptical arc with its center at the current 
position. The arc parameters (see below) together with a specified multiplier (£255) 
control the shape and size of the arc. The options allow the outline (DRO__OUT- 
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A 


GpiPolyFiUet example 2 (only 2 points plus current position provided) 

Figure 3.7 GpiPolySpline, GpiPolyFiUet Sharp, and GpiPolyFiUet. 


LINE), the interior (DRO_FILL), or both (DRO_OUTLINEFILL) to be drawn. The 
interior, if drawn, is filled using the AREABUNDLE attributes. The current 
position is not affected by this function. The multiplier is of type FIXED (see 
chapter 1). 
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B 



Sharpness * DE/EB 

Figure 3.8 GpiPolyFilletSharp Sharpness. 


GpiPartialArc 

This draws a straight line from the current position to the start point of the arc 
followed by a circular or elliptical arc with its center at a specified point. The arc 
parameters (see below), together with a specified multiplier (<255), control the the 
shape and size of the arc. The start and end points of the arc are defined by a 
specified positive start and sweep angle (in degrees) measured counterclockwise 
using the unit circle before application of the arc parameters (i.e., the specified 
angles will be modified by the arc parameters if these do not define a circular arc). 
The start angle is measured from the x-axis. The current position is updated to the 
end point of the arc. GpiPartialArc can be used to draw a pie slice (see the function 
DrawPieSlice in Figure 3-9) or a closed figure bounded by a chord and an arc (see 
the function DrawChordAndArcFigure in Figure 3-10). The multiplier and start 
and sweep angles are of type FIXED (see chapter 1). 

GpiPointArc 

This draws an arc through three points starting from the current position. The arc 
parameters (see below) control the the shape of the arc. The current position is 
updated to the end point of the arc. 


GpiBox 

This draws a box with diagonally opposite corners at the current position and a 
specified point. The comers of the box may be optionally rounded with a quarter 
ellipse defined by the rounding controls. If either or both rounding controls are 
zero, then no rounding occurs. If both are non-zero, then they define the horizontal 
and vertical full axes of the ellipse to be used for rounding. If they are non-zero 
and equal, then the corners are rounded using a quarter circle. The options allow 
the outline (DRO_OUTLINE), the interior (DRO_FILL), or both (DRO_OUT- 
LINEFILL) to be drawn. The interior, if drawn, is filled using the AREABUNDLE 
attributes. The current position is not affected by this function. 
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/* pieslice.c */ 

BOOL DrawPieSlice (HPS hps) 

{ 


/* Draw pie slice using 

the current arc parameters 


*/ 

/* 




*/ 

/* inputs: hps PS handle 



*/ 

/* 




*/ 

//define MULTIPLIER 

0x00028000 L 




//define STARTANGLE 

0x00300000 L 




//define SWEEPANGLE 

0x00400000L 




POINTL ptlPosn 


/* 

center point 

*/ 

BOOL fRet 


/* 

BOOL return code 

*/ 

ARCPARAMS arcpParms 


/* 

arc parameters 

*/ 

a rcpPa rms.1P = 500L; 
arcpParms.1Q = 500L; 
a rcpPa rms.1R = OL; 
arcpParms.IS = OL; 


/* 

set arc parameters 

*/ 

fRet = GpiSetArcParams 

( hps 

/* 

-PS handle 

*/ 


, &arcpParms 
); 

/* 

-arc parameters 

*/ 

ptlPosn.x = 3000L; 
ptlPosn ,y = 1000L; 
if(fRet) 


/* 

set center position 

*/ 

fRet = GpiSetCurrentPosition( hps 

/* 

-PS handle 

*/ 


, &ptlPosn 
); 

/* 

-coordinate point 

*/ 

if (fRet) 


/* 

draw radius and arc 

*7 

fRet = (BOOL)GpiPartialArcC hps 

/* 

-PS handle 

*/ 


, &ptlPosn 

/* 

-center position 

*7 


, MULTIPLIER 

/* 

-multipiier 

*7 


. STARTANGLE 

/* 

-start angle 

*/ 


, SWEEPANGLE 
); 

/* 

-sweep angle 

*/ 

if (fRet) 


/* 

draw radius back to 

center */ 

fRet = (BOODGpi Line( hps 

/* 

-PS handle 

*7 


, &ptlPosn 

/* 

-coordinate point 

*7 


); 

return (fRet); 

} 

Figure 3.9 DrawPieSlice Function. 

GpiOutlinePath 

This draws a line describing the outline of a path (see below). 

Are Parameters 

The arc parameters p, q, r, and s define a transform matrix that maps a unit circle 
to the required ellipse, thus: 

x' = p*x + r*y 


y'=s*x + q*y 




DRAWING PRIMITIVES AND ATTRIBUTES 


77 


charcfig.c */ 


BOOL DrawChordAndArcFigure(HPS hps) 

{ 

/* Draw closed figure bounded by a chord and an arc using the current arc */ 
/* parameters. */ 

/* */ 

/* inputs: hps PS handle */ 

/* */ 


//define MULTIPLIER 0x00028000L 

//define STARTANGLE 0x00300000L 

//define SWEEPANGLE 0x00400000L 

//define ENDANGLE (STARTANGLE + SWEEPANGLE) 


POINTL ptlPosn ; 

/* center point 

*/ 

BOOL fRet ; 

/* BOOL return code 

*/ 

ARCPARAMS arcpParms ; 

/* arc parameters 

*/ 

arcpParms.1P = 500 L; 



a rcpPa rms.1Q = 500L; 



a rcpPa rms.1R = 0 L; 



arcpParms.IS = OL; 

/* set arc parameters 

*/ 

fRet = GpiSetArcParams( hps 

/* -PS handle 

*/ 

, &arcpParms 
); 

/* -arc parameters 

*/ 

if (fRet) 

/* set line type invisible 

*/ 

fRet = GpiSetLineType( hps 

/* -PS handle 

*/ 

, LINETYPE_INVISIBLE 
\ . 

/* -line type 

*/ 

/ > 

ptlPosn.x = 3000L; 



ptlPosn.y = 1000L; 



if (fRet) 

/* move to arc end point 

*/ 

fRet = (BOOL)GpiPartialArc( hps 

/* -PS handle 

*/ 

, &ptlPosn 

/* -coordinate point 

*/ 

, MULTIPLIER 

/* -multiplier 

*/ 

, ENDANGLE 

/* -end angle 

*/ 

, OL 
) ; 

/* -sweep angle (zero) 

*/ 

if (fRet) 

/* set line type visible 

*/ 

fRet = (BOOL)GpiSet LineType( hps 

/* -PS handle 

*/ 

, LINETYPE SOLID 
); 

/* -line type 

*/ 

if (fRet) 

/* draw chord and arc 

*/ 

fRet = (BOOL)GpiPartialArc( hps 

/* -PS handle 

*/ 

, &ptlPosn 

/* -coordinate point 

*/ 

. MULTIPLIER 

/* -multiplier 

*/ 

. STARTANGLE 

/* -start angle 

*/ 

, SWEEPANGLE 

/* -sweep angle 

*/ 


); 


return (fRet); 

} 

Figure 3.10 DrawChordAndArcFigure Function. 

For greatest accuracy, the transform should be orthogonal (i.e., such that p*r + s*q 
= 0). Consider first a unit circle centered at the origin. This can be mapped to the 
required ellipse with major and minor axes of 2a and 2b along the x and y axis 
respectively by setting p=a, q=b, r=0 and s=0. 




OS/2 PRESENTATION MANAGER GPl 


i.e. x' = a*x 


y' = b*y 

This ellipse then can be rotated counterclockwise through R degrees by modifying 
these previous values, thus: p=aCosR, q=bCosR, r=-bSinR and s=aSinR. 

i.e. x' = aCosR*x - b8inR*y 

y' = aSinR*x + bCosr*y 

An unrotated and a rotated ellipse are illustrated in Figure 3-11. 

As arc parameters are specified as integers, a and b should be sufficiently large 
to scale the values of CosR and SinR such that precision is not lost by discarding 
the fractional part of the result. The overall size of the ellipse can then be 
controlled by scaling down using the arc multiplier parameter (with GpiFullArc 
and GpiPartialArc). 



p = 1500, q = 750, r = 0, § = 0 



p = 1500 Cos 30, q = 750 Cos 30, r = -750 Sin 30, s = 1500 Sin 30 
Figure 3.11 Arc Parameters. 
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GpiSetPel mi GpiQueryPel 

GpiSetPel is similar to the BitBlt and Gpilmage functions except it uses the 
LINEBUNDLE rather than the IMAGEBUNDLE attributes. It sets the pel at the 
specified position using the LINEBUNDLE color and mix attributes. GpiSetPel is 
never stored in a retained graphics segment but is always output directly to the 
device, regardless of drawing mode. Note also that GpiSetPel does not conform to 
the MetaFile interchange architecture and should not therefore be used when 
creating a MetaFile for interchange with other products (see chapter 11). 

GpiQueryPel is the reverse of GpiSetPel and returns the color index or RGB 
value (according to the logical color table mode) of the pel at the specified position. 
If the pel is not visible, because for example it is overlayed by another window, an 
error is returned. 


AREA DRAWING FUNCTIONS 
Area Bundle Attributes 

Areas are drawn using the AREABUNDLE (area bundle) attributes. The 
AREABUNDLE attributes and flags (parenthesized) are as follows: 

[Color (ABB_ COLOR) 

This specifies the area fill pattern foreground color. 


IBackColor (ABB_BACK_COLOR) 

This specifies the area fill pattern background color. 


usMixMode (ABB_MIX_MODE) 

This specifies the area fill pattern foreground mix mode. 


usBackMixMode (ABB_BACK_M!X_MODE) 

This specifies the area fill pattern background mix mode. 

usSet (ABB_$ET) 

This defines the id of the pattern set, logical font, or bitmap to be used for the area 
fill. An area fill operation can use a pattern from the standard pattern set, a 
particular character from a logical font, or a bitmap tagged with a set id (see 
chapter 4). A value of LCID_DEFAULT (zero) specifies default, which will initially 
reference the standard pattern set illustrated in Figure 3-12. 
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PATSYM_DENSE8 


PATSYM_DENSE7 


PATSYM_DENSE6 


PATSYM_DENSE5 


PATSYM_DENSE4 


PATSYM_DENSE3 


PATSYM_DENSE2 


PATSYM_DENSE1 








PATSYM.HALFTONE 


PATS YM_S OLID 


PATSYM_NOSHADE & PATSYM_BLANK 


PATS YM_DIAG4 


PATS YMJDIAG3 


PATSYM_DIAG2 


P ATS YM_DIAG 1 


PATSYM_HORIZ 


PATS YM_ VERT 


Figure 3.12 Standard Pattern Set. 


usSymboS (ABB_SYMBOL) 

This defines the pattern within the standard pattern set or the character codepoint 
within the logical font specified by the usSet attribute. If the current pattern set 
is a bitmap then the us Symbol attribute is ignored. 


ptIRefPoint (ABB„REF_POINT) 

This defines the pattern origin in world coordinates. Its initial default value is 
(0,0). The pattern origin can be outside the area to be filled. 

This attribute is intended to avoid area boundary discontinuities that might 
occur when part of a picture is scrolled using GpiBitBlt and the remainder is 
redrawn. The scroll distance should be converted from device to world coordinates 
using GpiConvert and used to adjust the pattern origin before redrawing the 
picture. Unfortunately transform rounding errors make it impossible to always 
guarantee complete freedom from all discontinuities. 
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Irea Primitives 

An area is drawn using the following sequence of functions, as illustrated by the 
function Dr aw Are a in chapter 1. 

GpiBeginArea 

GPI drawing calls defining one or more closed figures. 

GpiEndArea 

All boundaries are inclusive and form part of the filled area. 

If a figure inside an area bracket is not closed, GpiEndArea generates an 
automatic closure line from the end to the start of the figure. 

Only certain functions are valid within an area. These are basically functions 
that produce lines (including outline fonts) and certain attribute setting functions 
(see the IBM OS/2 Programming Reference for a complete list of valid functions). 
GpiBeginArea provides the following options: 

BAJBOUNDARY/BA_NOBOUNDARY specifies whether or not 
boundary lines are drawn in addition to the filled interior. 

BA_ALTERNATEYBA_WINDING specifies whether the fill should 
be performed using alternate or winding mode. This option is signifi¬ 
cant for areas defined by multiple overlapping figures. In alternate 
mode, a figure segment is filled if, counting from infinity to a point 
in the segment, the number of figure boundary line crossings is odd. 
Figure segments for which this number is even are not filled. 

In winding mode, the direction of the boundary lines is signifi¬ 
cant. Figure boundary lines drawn in one direction (e.g. clockwise) 
can be considered to have a weight of +1 and those in the opposite di¬ 
rection a weight of -1. A figure segment is filled if, counting from in¬ 
finity to a point in the segment, the net weight of the figure bound¬ 
ary line crossings is non-zero. Figure segments for which the net 
weight is zero are not filled. 

An area consisting of a six-pointed star defined by two triangles 
drawn using both BA_ALTERNATE and BAJWINDING mode is 
illustrated in Figure 3-13. 

Areas can also be drawn by defining a path and issuing GpiFillPath (see below). 

Areas are implemented internally by the system using path functions. Note that 
for IBM OS/2 Version 1.3 at least, there is an internal limit of 64K on the maximum 
size of a path and it is not possible to predict with any certainty when this limit 
will be reached. When reached, an error is returned and the error code 
PMERR_PATH_LIMIT_EXCEEDED is logged. 
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BA_ALTERNATE mod© BA_WINDING mod© 

Figure 3.13 Areas Drawn using BA_ALTEENATE and BA_WINDING mode. 


MARKER FUNCTIONS 

Markers are typically used for displaying points on a graph and are similar to 
characters except for the way in which they are positioned. Whereas characters 
are positioned by a reference point near the bottom left comer of the first character 
of a string, with each subsequent character positioned relative to that preceding 
it, markers are individually positioned by their marker box center. 

The system provides a standard marker set as illustrated in Figure 3—14. Alterna¬ 
tively a raster or outline font character can be used as a marker symbol. However, 
a font character used as a marker will be imperfectly positioned if its symbol 
definition is not positioned centrally within its character box. 


Marker Bundle Attributes 

Markers are drawn using the MARKERBUNDLE (marker bundle) attributes. The 
MARKERBUNDLE attributes and flags (parenthesized) are as follows: 


ICoIor (MBB.COLOR) 

This specifies the marker color. 


IBacRGoIor (MBB_BACKCOLOR) 

This specifies the marker box (or cell) background color. 


usMixMode (MBBJMXJIIODE) 

This specifies the marker mix mode. 
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X MARKS YM_GR.OSS 
+• MASKS YM_PLUS 
O MARKSYM_DIAMOND 
□ MARKS YM_SQUARE 
ap MARKSYM_SIXPOINTSTAR 
MARKSYM_EIGHTPOINTSTAR 

# MARKSYM_SOLIDDIAMOND 
■ MARKS YM_$OLIDSQUARE 

• MARKS YM_DOT 

O MARKS YM_SMAJLLCIRCLE 
MARKS YM_BLANK 

Figure 3.14 Standard Marker Set 


usBackMixMode (MBB_BACK_MIX_MODE) 

This specifies the marker box (or cell) background mix mode. 

usSet (MBB_SET) 

This defines the id of the marker set or font to be used for drawing markers. A 
value of zero (LCID_DEFAULT) specified with GpiSetMarkerSet sets the current 
marker set to default. A value of zero specified with GpiSetAttrs or GpiSetDefAttrs 
sets the current or default marker set back to the standard marker set (i.e., the 
initial default). 


usSymbol (MBB_SYMBOL) 

This specifies the codepoint of the marker symbol within the current marker set 
(or character within the font) to be used for drawing markers. 


sizfxCell (MBB_BOX) 

This specifies the marker box width and height in world coordinates. These control 
the size of markers drawn using outline font characters. For markers drawn using 
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the system (raster) marker set or raster font characters, the marker box attribute 
is ignored. Although the marker box dimensions are of type FIXED for consistency 
with the character box attribute, for marker box dimensions the fractional part 
should always be specified as zero. This is because the 'set marker set’ order stored 
in MetaFiles and retained segments is unable to support a fractional part and, in 
such situations, the fractional part will be discarded. 

Marker Primitives 

Markers are drawn using the GpiMarker and GpiPolyMarker functions described 
below. 

GpiMarker 

This draws a marker at a specified position and updates the current position. 

GpiPolyMarker 

This draws a series of markers at specified positions and updates the current 
position to that of the last marker. A count of zero is valid and in which case the 
function will be treated as a no-op. This provides a superset of the function 
provided by GpiMarker. 


IMAGE AND BITBLT FUNCTIONS 
Image Bundle Attributes 

A GPI image is a rectangular array of monochrome (1 bit per pel) pixel data. GPI 
images are drawn using the IMAGEBUNDLE (image bundle) attributes. 

BitBlt operations provide an alternative, and improved, method of performing 
image operations. The IMAGEBUNDLE foreground and background color attri¬ 
butes are also used in certain BitBlt operations involving monochrome bitmaps 
(see below). 

These functions return an error if issued to a device such as a plotter that does 
not support raster operations. See chapter 5 for BitBlt programming examples and 
a description of bitmaps. 

The IMAGEBUNDLE attributes and flags (parenthesized) are as follows: 

IColor (IBB_CO10R) 

This specifies the image foreground color. 

IBackGolor (IBB_BACK_C0LOR) 

This specifies the image background color. 



DRAWING PRIMITIVES AND ATTRIBUTES 


usMsxMode (IBB_M!X_MODE) 

This specifies the image foreground mix mode. 
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usBaekMixMode (IBB_BACK_M!X_MODE) 

This specifies the image background mix mode. 


Image and BifiSf irawSng Primitives 

The image and BitBlt drawing functions are described below. 


Gpilmage 

This draws a rectangular pixel image with its top left origin at the current 
position. The image data consists of a single plane of data with one bit per pel 
in application memory. The data is arranged as an array of bytes, where the first 
byte represents the first eight pixels (of the top row) to be drawn from the 
current position, with the most significant bit of each byte representing the 
leftmost pel. The bits in the final byte of each row are padded, as necessary, to 
a byte boundary. The image is drawn with one’ bits displayed using the IM- 
AGEBUNDLE foreground mix and color and zero’ bits the background mix and 
color. 

Typically, the three separate planes of an RGB image would be drawn in turn 
with a foreground mix of FM_OR, background mix of BMJLEAVEALONE, and 
foreground color of CLR_RED, CLR_GREEN, and CLR_BLUE respectively. 

The Gpilmage function is provided primarily for reasons of compatibility with 
earlier products. The BitBlt functions are generally considered to be more suitable 
for the majority of new applications. 

GpiBitBit 

This function enables the rapid transfer of a rectangular array of pixel data 
between a source and target pixel device or bitmap. The source and target of a 
GpiBitBit operation can include any of the following combinations: 

a bitmap and device; 
a device and bitmap; 
the same device; 
the same bitmap; and 
different bitmaps. 

Bitmaps are device dependent objects and both the source and target of any BitBlt 
operation must be owned’ by the same device (e.g., for the display, source and 
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target must be either a display window or a bitmap owned by the display device). 
Bitmap ownership is established at creation time by the PS (and associated DC) 
specified with GpiCreateBitmap and GpiLoadBitmap. 

It is possible to transfer bitmap ownership from one device to another using 
GpiSetBitmap to deselect the bitmap from the PS/DC for the old device (if selected) 
and select it to a PS/DC for the new device (see chapter 5). 

A bitmap can be created in any one of the four standard formats (i.e., a single 
plane with 1, 4, 8, or 24 bits per pel) or may be in a device internal format that is 
not one of the standard formats. The format with a single plane and 1-bit per pel 
is referred to as a monochrome bitmap. 

When using GpiBitBlt with a color source and monochrome target or with a 
monochrome source and output device surface or color target, color conversion 
occurs. The rules of color conversion are as follows: 

Monochrome source to monochrome bitmap target—No color con¬ 
version is performed, the IMAGEBUNDLE attributes are not used. 

Monochrome bitmap source to monochrome target device sur¬ 
face—Color conversion is performed using the target IMAGEBUN¬ 
DLE background and foreground colors for the source ‘O' and *Y 
bits respectively. Note that this was not always the case and some 
older drivers may not provide this conversion. This change was in¬ 
troduced to provide consistency between BitBlt operations per¬ 
formed on a color display and those performed on a monochrome 
printer. 

Monochrome source to color target—Color conversion is per¬ 
formed using the target IMAGEBUNDLE background and fore¬ 
ground colors for the source ‘O’ and T bits respectively. 

Color source to monochrome target—Color conversion is per¬ 
formed using the source IMAGEBUNDLE background color to deter¬ 
mine which source bits are background (all other bits are assumed 
to be foreground) and the target IMAGEBUNDLE foreground and 
background colors for the source foreground and background bits 
thus obtained. 

Monochrome pattern to color target (see below)—Color conversion 
is performed using the target AREABUNDLE background and fore¬ 
ground colors for the pattern ‘O' and T bits respectively. 

Color source to color target—Color conversion is not performed, 
the IMAGEBUNDLE attributes are not used. 

Note that if part of the source is unavailable because, for example, it is overlayed 
by another window on the display screen, then this part of the target is undefined 
and no error is returned by GpiBitBlt. 

The GpiBitBlt parameters are as follows: 
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LONG GpiBitBlt( HPS hpsTarget 
, HPS hpsSource 
, LONG ICount 
, PPOINTL aptlPoints 
, LONG IRop 
, ULONG flOptions 
); 


hpsTarget and hpsSource These identify BitBlt source and target presentation 
spaces. If the Rop mix value does not require a source (e.g., ROP_PATCOPY or 
ROP_ZERO) then the source PS may be specified as NULL. Source or target 
may be associated with a display window DC or an OD_DIRECT DC for any 
raster device. Where the source or target is a bitmap, the bitmap must be 
selected into an OD_MEMORY DC associated with the specified PS. The DC 
associated with the target PS can also be a DC of type OD_QUEUED, 
OD_METAFILE, or OD_METAFILE_NOQUERY. A MetaFile containing a re- 
corded GpiBitBlt operation will not conform to the MetaFile interchange archi¬ 
tecture (see chapter 11). 

SCount and aptlPoints These identify an array of 2, 3, or 4 coordinate points (in 
device coordinates) providing a target and optional source rectangle. If the Rop mix 
value does not require a source (e.g., ROP_PATCOPY or ROP_ZERO) then only 
two points are required. If three coordinates are supplied then source and target 
are assumed to be the same size and if all four coordinates are supplied, then the 
source and target may be different sizes to allow stretching or compression of the 
source bitmap data. As GpiBitBlt coordinates are specified as device coordinates, 
they are unaffected by the GPI transforms. 

IRop This specifies the Rop (raster operation) mix mode value and optionally 
allows a monochrome pattern (defined by the AREABUNDLE) to be included in 
addition to (or in place of) the source bitmap, providing a Three-way' BitBlt 
operation. 

The Rop code mix value is determined by constructing a truth table containing 
all combinations of input Pattern (P), Source (S), and Target Original Value (O) for 
any pixel and specifying the New Target Value (T) required for each combination. 
The number thus obtained from the eight bits defining T provides the Rop code 
value. 

For example, the Rop code required to replace the target with pattern fore¬ 
ground or background at each source pixel that is T (i.e., if S=T, T=P) and to leave 
the target unchanged at every source pixel that is 'O' (i.e., if S=‘0' T=0) is 0x00E2L 
as illustrated below. 
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(S) 

(0) 

CD 

0 

0 

0 

0 

0 

0 

1 

1 

0 

1 

0 

0 

0 

1 

1 

0 

1 

0 

0 

0 

1 

0 

1 

1 

1 

1 

0 

1 

1 

1 

1 
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The system provides predefined symbolic constants for the following most fre¬ 
quently used Rop mix values: 


ROP_SRCCOPY 

(OxOOCCL) 

T=S 

ROP_SRCPAINT 

(OxOOEEL) 

T=S | O 

ROP_SRCAND 

(0x0088L) 

T=S&0 

ROP_SRCINVERT 

(0x0066L) 

T=S a O 

ROP_SRCERASE 

(0x0044L) 

T=S&~0 

ROP_NOTSRCCOPY 

(0x0O33L) 

o 

l 

ii 

EH 

RQPJMOTSRCERASE 

(OxOOllL) 

T=~S&~0 

ROP_MERGECOPY 

(OxOOCOL) 

T=P&S 

R0PJV1ERGEPAINT 

(OxOOBBL) 

T=~S|O 

ROP_PATC OPY 

(OxOOFOL) 

T=P 

ROP_PATPAINT 

(OxOOFBL) 

T=~S|P|0 

ROP_PATINVERT 

(0x005AL) 

T=O a P 

ROP_DSTINVERT 

(0x0055L) 

T=~0 

ROP_ZERO 

(OxOOOOL) 

T=0 

ROP_ONE 

(OxOOFFL) 

T=1 


For determining the effect of the Rop code on a color target, the target must be 
regarded as multiple planes, each of one bit per pel (rather than one plane with 
multiple bits per pel), with each plane processed separately. 
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flOptions The options are applicable only to compression and control the appear¬ 
ance at positions where pels are eliminated: 

BBO_OR specifies that multiple eliminated pels are ORed with a 
remaining pel (this ensures that when ‘O' is foreground, background 
*Y pels are preserved). 

BBO_ANB specifies that multiple eliminated pels are ANDed 
with a remaining pel (this ensures that when *Y is foreground, back¬ 
ground ‘0* pels are preserved). 

BBO_IGNORE specifies that eliminated pels are ignored (this is 
useful for color). 

Note that GpiBitBlt, as well as being unaffected by the GPI transforms and not 
conforming to the MetaFile interchange architecture, is always output directly to 
the device and never stored in a retained segment, regardless of drawing mode. 
These restrictions do not apply to GpiWCBitBlt (described below). 


GpiWCBitBIt 

The world coordinate BitBlt function GpiWCBitBlt is very similar to GpiBitBlt but 
has a number of important differences as follows: 

1. Whereas like GpiBitBlt, the source rectangle coordinates are specified 
as device coordinates, the GpiWCBitBlt target rectangle coordinates 
are specified in world coordinates and are consequently subject to all 
of the GPI transforms. As a consequence of this, the aptlPoints array 
must always include all four source and target rectangle coordinates 
and ICount must always be specified as four. The operation does not 
(for IBM OS/2 Version 1.3 at least) support rotation and shear. Note 
that a change to the Default Viewing Transform would result in 
GpiWCBitBlt output being correctly positioned relative to other 
graphics output, whereas GpiBiBlt output would be incorrectly posi¬ 
tioned. 

2. As a consequence of the above, target coordinates for GpiWCBitBlt are 
inclusive at all boundaries whereas GpiBitBlt target coordinates are 
inclusive at the bottom and left and exclusive at the top and right 
boundaries. The effect of this in practice is that with page units of 
PU_PELS and all transforms set to identity, the top right GpiBitBlt 
target coordinates would need to be one greater than the correspond¬ 
ing GpiWCBitBlt coordinates for an identical operation. 

3. The GpiWCBitBlt source parameter is a bitmap handle rather than a 
PS handle. The source, therefore, can only be a bitmap and this should 
not be selected into a PS/OD_MEMORY DC. The source and target of 
a GpiWCBitBlt operation are therefore limited to the following combi¬ 
nations: 
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a bitmap and device; 
the same bitmap; and 

different bitmaps owned by the same device. 

Bitmap ownership is transferred in the same way as for GpiBitBlt. If 
a bitmap is owned by a different device, ownership is transferred by 
selecting the bitmap into a PS/DC for the new device (using 
GpiSetBitmap). The difference is that the bitmap should be deselected 
before issuing GpiWCBitBlt. 

4. For a GpiWCBitBlt operation from a color source to a monochrome 
target, no source IMAGEBUNDLE attributes are available. Color 
conversion is therefore performed using the IMAGEBUNDLE attri¬ 
butes of the target PS and these are used to determine which source 
bits are background (all other bits are assumed to be foreground). 

5. Unlike GpiBitBlt, GpiWCBitBlt can be stored as a drawing order 
inside a retained segment and conforms to the MetaFile interchange 
architecture. 


PATHS 


Paths are picture functions that can be used for any of the following operations: 

• Drawing a filled area (instead of using GpiBeginArea/GpiEndArea). 

• Drawing an unfilled outline that can include outline font characters. 

• Defining an arbitrarily complex non-rectangular shape as a clip 
boundary. 

• Drawing geometric wide lines. These are lines, the appearance of 
which is controlled by the line join, line end, and geometric line width 
LINEBUNDLE attributes. Geometric line width can be defined by an 
application and is subject to all the normal GPI transforms (scaling, 
etc.). The resulting geometric wide line' envelope definition is con¬ 
tained in a modified path that can be filled in the same way as a 
normal path to display the wide line. 

Geometric Wide Line Attributes {used with Paths) 

The LINEBUNDLE attributes and flags (parenthesized) used with paths for 

constructing geometric wide lines are as follows: 

IGeomWidth (LBB_GEOM_WIDTH) 

This specifies the geometric line width attribute in world coordinates. 

usEnd (LBB_END) 

This specifies the line end and attribute as one of: 

LINEEND_FLAT; 



DRAWING PRIMITIVES AND ATTRIBUTES 


91 


LINEEND_SQUARE; and 
LINEEND_ROUND. 

usJoin (LBB.JOIN) 

This specifies the line join attribute as one of: 
LINEJOIN_BEVEL; 
LINEJOIN_ROUND; and 
LINEJOIN_MITRE. 


Path Definition 

A path is defined by issuing the drawing primitives and attributes for the required 
(area, outline, clip path, or geometric wide line) path figures between: 


GpiBeginPath; and 
GpiEndPath. 


GpiBeginPath and GpiEndPath, together with the path definition primitives can 
be output directly in non-retained mode, accumulated in a retained segment, or 
both, depending on the drawing mode. The path is created (but not displayed) 
when the path definition primitives are actually output, whether directly, or from 
a retained segment. Clearly, when stored in a retained segment, the same path can 
be created at will merely by redrawing the segment. Note that the primitives (e.g., 
lines) inside a path bracket merely contribute to the path definition, and are not 
actually displayed unless the completed path is subsequently drawn (e.g., using 
GpiOutlinePath). 

Path definition primitives (and orders stored inside a path in a retained seg¬ 
ment) are specified in world coordinates and are therefore subject to all the normal 
GPI transforms. However, once the path is created by outputting the path defini¬ 
tion primitives, it becomes fixed in device coordinates and unaffected by subse¬ 
quent transform changes. 

Any path can include outline font characters which, though normally filled, in 
the context of a path bracket provide only the outline of the individual characters 
as part of the path definition. 

Only certain functions are valid inside a path. These are basically calls that 
produce lines (including outline fonts) and certain attribute setting functions (see 
the IBM OS/2 Programming Reference for a complete list of valid functions). 

Note that for IBM OS/2 version 1.3 at least, there is an internal limit of 64K on 
the maximum size of a path, and it is not possible to predict with any certainty 
when this limit will be reached. When reached, an error is returned and the error 
code PMERR_PATH_LIMIT_EXCEEDED will be logged. 
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Paths are typically destroyed the first time they are used (see below). 


Path Areas 


To draw an area using paths, a path containing one or more figures describing the 
required area shape must first be created. A path area fill operation is then 
performed using the AREABUNDLE attributes by: 

GpiFillPath 

On completion of the fill, the path is destroyed. 

The GpiFillPath options FPATH_ALTERNATE and FPATH_WINDING control 
whether the fill is performed in alternate or in winding mode and are equivalent 
to the GpiBeginArea options described earlier. An example of area fill using path 
functions is illustrated by the function DrawPathArea in Figure 3-15. 


/* 

BOOL DrawPathArea(HPS hps) 
{ 


patharea.c */ 


/* Create a path defining a six pointed star made up of two triangles, and 
/* f ill it using the FPATH_WINDING option. Note that filling this with the 
/* FPATH_ALTERNATE option would leave the centre portion unfilled. 

/* 


/* inputs: hps PS handle 
/* 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


BOOL fRet 
POINTL ptlPoint 
POINTL aptlPoints[3] 


/* 

BOOL return 

code 

*/ 

/* 

coordinate 

point 

*/ 

/* 

coordinate 

point array 

*/ 


fRet = GpiBeginPath( hps 
, 1L 
); 


/* 

begi n 

path 

*/ 

/* 

-PS he 

indie 

*/ 

/* 

- path 

id (must be 1) 

*/ 


ptlPoint.x-lOOL; /* define path area shape */ 

ptlPoint .y = 100L; 
if (fRet) 

fRet = GpiSetCurrentPosition(hps, &p11 Point); 


aptlPoints[0].x = 200L 
aptlPoints[0].y = 273L 
aptlPoints[l].x = 300L 
aptlPoints[l].y = 100L 
aptlPoints[2].x = 100L 
aptlPoints[2].y = 100L 


if (fRet) 

fRet = GpiPolyLine(hps, 3L, aptlPoints) != GPI_ERR0R; 


Figure 3„15 DrawPathArea Function. 
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ptlPoint.x = 100L; 
ptlP oint .y = 215L; 
if (fRet) 

fRet = GpiSetCurrentPosition(hps, &ptlPoint); 

aptlPoints[0].x = 300L; 
aptlPolnts[0].y = 215L; 
aptlPoints[1].x = 200L; 
aptlPoints[1].y = 042L; 
aptlPoints[2].x = 100L; 
aptlPoints[2] .y = 215L; 
if (fRet) 

fRet = GpiPolyLine(hps, 3L, aptlPoints) != GPI_ERR0R; 


if (fRet) 

/* 

end path 

*/ 

fRet = GpiEndPath(hps ); 

/* 

-PS handle 

*/ 

if (fRet) 

/* 

set color 

*/ 

fRet = GpiSetColor(hps , CLR_RED); 




if (fRet) 

/* 

fill path 

*/ 

fRet = (BOOL)GpiFi11 Path( hps 

/* 

-PS handle 

*/ 

, 1L 

/* 

-path id (must be 1) 

*/ 

, FPATH WINDING 

/* 

-fill option 

*/ 


) ; 

return(fRet); 

} 


Figure 3d 5 (continued) 


Patti Outlines 

To draw an outline using paths, a path containing one or more figures defining the 
required outline line shape must first be created. A path outline operation is 
performed using the LINEBUNDLE attributes by: 

GpiOutlinePath 

On completion of drawing the outline, the path is destroyed. 

This function can be used to draw an unfilled outline of an entire path including 
that of any outline font characters in the path that would otherwise be filled. 


geometric Wide Lines 

To draw a geometric wide line using paths, a path containing one or more figures 
describing the required shape must first be created. Any closed figures in the 
definition should be explicitly closed using GpiCloseFigure to ensure that line join 
rather than line end attributes are used at the join between the start and end 
points. The path must next be modified' using the geometric line width, line join, 
and line end LINEBUNDLE attributes. This is accomplished using 
GpiModifyPath. The result is a path describing the envelope of a geometric wide 
line that can then be filled (and deleted) in the normal way using GpiFillPath. 
Alternatively, the original path can be stroked (i.e., modified and filled) in a single 
operation using GpiStrokePath. 
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As mentioned above, the result of GpiModifyPath is a path describing the 
envelope of a geometric wide line that can be filled the normal way. However, a 
modified path is still a normal path and any valid path operation (including 
GpiModifyPath again) can be performed on it if required. Note that the fill 
associated with GpiStrokePath is always performed using winding mode, whereas 
a path modified and filled separately using GpiModifyPath and GpiFillPath can 
use either alternate or winding mode for the fill operation. The main advantage of 
GpiStrokePath is that it has a lower memory overhead than the two separate 
operations and may therefore be successful under conditions where 
GpiModifyPath and GpiFillPath might fail due to insufficient memory. 

Line join attributes are applied to line joins regardless of primitive type (e.g., to 
join a line to an arc). The different line end and line join attributes are illustrated 
in Figure 3-16. An example of drawing geometric wide lines using path functions 
is illustrated by the function BrawGeomWideLine in Figure 3-17. 


Clip Pattis 

To create a clip path, a (normal) path containing one or more figures describing the 
required clip shape must first be created. A path is converted to a clip path using: 

GpiSetClipPath 



LINEENDJJLAT 



LINEBND_SQUARE 



LINEEND JIOUNB 



UNEJ0JN3UTRE LINEJOIN_ROUNB UNEJOINJBEVEL 

Figure 3.16 Line-End and Line-Join Geometric Wide Line Attributes. 
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/* geomline.c */ 

BOOL DrawGeomWideLine(HPS hps, BOOL flOptions) 


{ 


/* Create 

a path containing the required 

lines and optionally close the 

*/ 

/* figure 

. Modify the path using the appropriate geometric wide line 

*/ 

/* attributes and fill it to draw a geometric wide line. 

*/ 

/* 



*/ 

/* inputs 

: hps PS handle 


*/ 

/* 

flOptions options (TRUE for 

close figure) 

*/ 

/* 


*/ 

BOOL 

fRet ; 

/* BOOL return code 

*/ 

POINTL 

ptlPoint ; 

/* coordinate point 

*/ 

POINTL 

aptlPoints[5] ; 

/* coordinate point array 

*/ 

LINEBUNDLE 1bndLineBundle ; 

/* line bundle 

*/ 



/* begin path 

*/ 

fRet = 

GpiBeginPath( hps 

/* PS handle 

*/ 


, 1L 

/* path id must be 1 

*/ 


); 


ptlPoint.x = 200L; /* define path (line) shape */ 

ptlPoint.y = 100L; 
if (fRet) 

fRet = GpiSetCurrentPosition(hps, &ptlPoint); 


aptlPoints[0].x = 100L; 
aptlPoints[0].y = 100L; 
aptlPoints[l].x = 100L; 
aptlPoints[1].y = 300L; 
aptlPoints[2].x = 300L; 
aptlPoints[2].y = 300L; 
aptlPoints[3].x = 300L; 
aptlPoints[3].y = 100L; 
aptlPoints[4].x = 200L; 
aptlPoints[4].y = 100L; 
if (fRet) 

fRet = GpiPolyLine(hps, 5L, aptlPoints) != GPI_ERR0R; 


if (fRet && flOptions) 

/* 

optional close figure 

*/ 

fRet = GpiCloseFigure(hps ); 

/* 

-PS handle 

*/ 

if (fRet) 

/* 

end path 

*/ 

fRet = GpiEndPath(hps); 

/* 

-PS handle 

*/ 

1bndLineBundle.1GeomWidth = 20L 




1bndLineBundle.us End = LINEEND_ROUND 




1bndLineBundle.usJoin = LIN EJ 01N_B EV E L 




if (fRet) 




fRet = GpiSetAttrs( hps 

/* 

set geometric line attributes 

*/ 

, PRIM LINE 

/* 

-attribute type 

*/ 

, LBB GEOM WIDTH 

/* 

-attributes mask 

*/ 

1 LBB END 




LBB JOIN 




, 0L 

/* 

-defaults mask 

*/ 

, &1bndLineBundle 

/* 

-attribute bundle 

*/ 


); 


Figure 3.17 DrawGeomWideLine Function. 
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if (fRet) 

/* 

set clip path 

*/ 

fRet = GpiModifyPath( hps 

/* 

-PS handle 

*/ 

, 1L 

/* 

-path control 

*/ 

, MPATH STROKE 
); 

/* 

-options 

*/ 

if (fRet) 

/* 

set color 

*/ 

fRet = GpiSetColor(hps, CLR_RED); 




if (fRet) 

/* 

fill path 

*/ 

fRet = (BOOL)GpiFi11 Path( hps 

/* 

-PS handle 

*/ 

, 1L 

/* 

-path id (must be 1) 

*/ 

, FPATH_WINDING 

/* 

-fill option 

*/ 


); 


return(fRet); 

} 

Figure 3.17 (continued) 

GpiSetClipPath has options, SCP_ALTERNATE and SCP_WINDING, controlling 
whether the clip path is constructed using alternate or winding mode. These are 
similar to the GpiBeginArea options described earlier. Other options, SCP_RESET 
and SCP_AND, together with the path control flag parameter (OL or 1L) specify 
whether the existing clip path is to be reset to infinity or modified to the intersec¬ 
tion of the existing clip path and the new path definition. 

Once converted to a clip path, the original path is deleted. The clip path is not a 
normal path and is not available for use with normal path functions such as 
GpiFillPath. An example of clip path definition is illustrated by the function 
CreateClipPath in Figure 3—18. 


/ clippath.c */ 

BOOL CreatedipPath(HPS hps) 

{ 


/* Create a path defining a six pointed star made 

up 

of two triangles and 

*/ 

/* select it as the clip path. 



*/ 

/* 



*/ 

/* inputs: hps PS handle 



*/ 

/* 



*/ 

BOOL fRet ; 

/* 

BOOL return code 

*/ 

POINTL ptlPoint ; 

/* 

coordinate point 

*/ 

POINTL aptlPoints[3] ; 

/* 

coordinate point array 

*/ 


/* 

begin path 

*/ 

fRet - GpiBeginPath( hps 

/* 

PS handle 

*/ 

, 1L 
); 

/* 

path id must be 1 

*/ 

ptlPoint.x = 100L; 

/* 

define path clip shape 

*/ 

ptlPoint.y = 10 0 L; 




if (fRet) 





fRet = GpiSetCurrentPosition(hps, &pt 1 Point); 


Figure 3.18 CreateClipPath Function. 
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aptlPointsEO] .x = 200L; 
aptlPoints[0].y = 273L; 
aptlPoints[l].x = 300L; 
aptlPoints[l].y = 100L; 
aptlPoints[2].x = 100L; 
aptlPoints[2].y = 100L; 

if (fRet) 

fRet = GpiPolyLine(hps, 3L, aptlPoints) != GPI_ERR0R; 

ptlPoint.x = 100L; 
ptlPoint.y = 215L; 
if (fRet) 

fRet = GpiSetCurrentPosition(hps , &ptlPoint); 


} 


aptl Poi nts [0].x = 300L; 
aptl Poi nts [0].y = 215L; 
aptl Poi nts[l] .x = 200L; 
aptl Poi nts[l] .y = 042L; 
aptl Poi nts E2].x = 100L; 
aptl Poi nts C 23.y = 215L; 
if (fRet) 

fRet = GpiPolyLine(hps, 3L, aptlPoints) != GPI_ERR0R; 


if (fRet) 

fRet = GpiEndPath(hps); /* end path */ 

if (fRet) /* set clip path */ 

fRet = GpiSetClipPath( hps /* -PS handle */ 

> 1L /* -path control */ 

, SCP_WINDING /* -options */ 

| SCP_AND 
); 

return(fRet); 


Figure 3.18 (continued) 





Fonts 


Fonts are resources that allow text to be displayed in a variety of sizes, typefaces 
(e.g., Roman, Courier), and styles (italic, bold, etc.). Raster font characters have fixed 
size, whereas outline font characters can be scaled to any size using the character 
box attribute and GPI transforms. Individual outline font characters or text strings 
can be scaled independently or as part of an entire graphics picture or text page. 

The GPI enables an application to specify the font to be used for drawing: 

• Text. 

• Characters within a graphics picture. 

• Markers. 

® Area fill patterns. 

In the case of markers and patterns, font characters may be used in place of 
markers and patterns from the standard marker and pattern sets. A font character 
designed for text, however, may not be ideally suited for use as a marker that 
requires precise positioning of its center, as the font design may not position a 
character symbol centrally within its definition space. 

Fonts may be shared by all applications across the entire system, relieving 
applications and MetaFiles of the need to carry the individual character glyph 
definitions. They need be concerned only with the attributes (facename, point size, 
etc.) of the required fonts. 

Font sizes are traditionally specified as the visible character height on the 
output device in points, where a point is a printers’ point measuring 1/72 inches 
(a 10 point font, for example, would therefore have a height of 10/72 or 0.139 
inches). Font point size is roughly equivalent to the maximum baseline extent (i.e., 
the sum of the maximum ascender and maximum descender) in device coordi¬ 
nates, but this is only an approximation. Font point size is not, in fact, precisely 
defined in terms of any measurable characteristic of a visible character. 
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Characters output from an application may be displayed using fonts from any 
of the following sources: 

1. The default Courier system outline font. 

2. A font from a user supplied font file. This can include a raster font 
created using the Font Editor and, for IBM OS/2 Version 1.3, Adobe 
Type 1 Outline fonts (these are supplied with OS/2 and can be also 
purchased independently). An Adobe Type 1 font is supplied as an 
.AFM (Adobe Font Metrics) and a .PFB (Postscript Font Binary) file, 
which are in the same format as soft fonts downloaded by the pscript 
driver. These are similar to the .PSF files described below. User 
supplied fonts of either type may be installed using the Control Panel 
or loaded using GpiLoadFonts. 

3. A device font (i.e., a font suitable for use with only one particular 
device). 

Device fonts can include fonts built into the device hardware or driver, 
provided on a separate device font card or cartridge, or provided as 
downloadable 'soft fonts’ on diskette. See chapter 12 for a discussion of 
printer fonts. 

Normally a raster or outline device font will be provided as the default 
font for a device. Devices that do not provide any device fonts will 
normally use a built-in system Courier raster font as their default. 

4. A generic font from a system font file. These are pre-installed via the 
Control Panel or can be loaded using GpiLoadFonts. 

On IBM OS/2 Version 1.3, the following pre-installed system font files 
are provided for use with Presentation Manager: 

courier, fon; 

times.fon; 

helv.fon; 

sysmono.fon; 

courier, psf; 

helvetic.psf; and 

timesnrm.psf. 

Courier.fon, times.fon, helv.fon, and sysmono.fon provide a range of 
raster fonts with various point sizes and device resolutions and the 
following Facenames (or typefaces): 

Courier; 

Helv; 

Tms Rmn; and 
System Monospaced. 
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The This Rmn and Helv fonts are proportionally spaced whereas 
Courier and System Monospaced are monospaced (i.e., fixed pitch). 
The .PSF files are a compiled version of the .AFM and .PFB files 
described above. The courier.psf, helvetic.psf and timesnrm.psf files 
are provided with IBM OS/2 Version 1.3 and provide a range of Adobe 
Type 1 Outline fonts with the following Facenames: 

Courier; 

Courier Italic; 

Courier Bold; 

Courier Bold Italic; 

Helvetica™; 

Helvetica Italic; 

Helvetica Bold; 

Helvetica Bold Italic; 

Times New Roman™; 

Times New Roman Italic; 

Times New Roman Bold; and 

Times New Roman Bold Italic. 

These same fonts also support the following previously supported 
outline font Facenames for compatibility with 1.1 and 1.2 applications. 

Helv; 

Helv Italic; 

Helv Bold; 

Helv Bold Italic; 

Tms Rmn; 

Tms Rmn Italic; 

Tms Rmn Bold; and 
Tms Rmn Bold Italic. 

PUBLIC AND PRIVATE FOOTS 


Fonts may be either public or private. A public font is one that is available to all 
application processes within the system whereas a private font is available only to 
the single application process from which it was loaded. External font files, 
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including both system and user supplied font files, can be installed as public fonts 
(and deleted) using the Control Panel or loaded as private fonts from an applica¬ 
tion using GpiLoadFonts. All device fonts are public fonts. 

It is recommended that applications should normally use public rather than 
private fonts. This is because private fonts are not available on a different process 
(e.g., the print process) from that on which they were loaded. They will not, 
therefore, be available to print jobs with data type PM_Q_STD that are printed 
via the spooler (print jobs with data type PM_Q_RAW will print private fonts 
successfully but PM_Q_STB is the recommended method of printing). 


monospaced mu proportional fonts 

Monospaced fonts are fonts for which every character has the same width, whereas 
proportional fonts provide characters with different widths according to the indi¬ 
vidual character shapes. Proportional fonts are generally considered to produce 
text with a much more pleasing appearance than that obtained using monospaced 
fonts but monospaced fonts are useful in situations where vertical alignment of 
characters is important (e.g., for computer programs). 


RASTER AND OUTLINE FONTS 

Raster fonts are fonts for which each character is defined as a fixed size bitmap or 
rectangular pixel image. Outline fonts are fonts for which each character is defined 
by a sequence of vector strokes and curves defining a closed figure that is 
optionally filled. Raster (or image) font characters are fixed size whereas outline 
(or vector) font characters are scalable and are transformed by the character box 
attribute and the current transforms. 

On IBM OS/2 Version 1.2, the outline fonts provided (originally within cou- 
rier.fon, helv.fon, and times.fon) were only really suitable for displaying large 
characters. When scaled to a small size, rounding errors caused the stroke 
thickness to vary and their appearance became rather ugly. This was remedied by 
the Adobe Type Manager™ provided with IBM OS/2 1.3 that supports Adobe Type 
1 Fonts enabling outline fonts to be used to display high quality text over a wide 
range of sizes, from quite small to very large. 

The Adobe Type 1 Fonts also provide kerning support. This is an additional 
refinement of proportional spacing which, for certain character pairs (e.g., Ta, To, 
Tr, We, and Yo), allows one character to overhang another providing a further 
improvement in the text appearance (see Figure 4-1). The function KemCharStr- 
ing in Figure 4-2 is equivalent to GpiCharString with kerning adjustment applied 
to each pair of characters for which kerning information is available. This function 
issues GpiQueryWidthTable to query the width table for all the characters in the 
codepage. It then queries the font metrics to determine the number of kerning 
pairs available before querying issuing GpiQueryKerningPairs to obtain the kern- 
ing pair information. An array of widths for the characters to be displayed is then 
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To AVAIL 
To AVAIL 

Figure 4.1 Kerned and Unkemed Text. 


/* kernchar.c */ 

BOOL KernCharString(HPS hps, LONG ICount, PCH pchString) 

{ 


/* Display 

the character string with the appropriate 

kerning adjustments. 

*/ 

/* 




*/ 

/* inputs: 

hps PS handle 



*/ 

/* 

ICount count of characters 


*/ 

/* 

pchString character string 


*/ 

/* 




*/ 

BOOL 

fRet = FALSE 


/* BOOL return code 

*/ 

FONTMETRICS fmMetrics 


/* font metrics 

*/ 

PLONG 

alWidths = NULL 


/* character width array 

*/ 

PKERNINGPAIRS akrnprs = NULL 


/* kerning pair array 

*/ 

PLONG 

alWidthTable = NULL 


/* width table 

*/ 

LONG 

i 


/* loop variable 

*/ 

LONG 

J 


/* loop variable 

*/ 




/* allocate memory for 

*/ 

alWidths 

= malloc((SH0RT)10ount*sizeof(L0NG)); 

/* character string width 

*/ 




/* array 

*/ 

if (alWidths!=NULL) 


/* allocate memory for 

*/ 

alWidthTable = mal1oc(256*sizeof(LONG)); 

/* width table 

*/ 

if (alWidthTable!=NULL) 


/* query width table 

*/ 

fRet = 

GpiQueryWidthTable( hps 


/* -PS handle 

*/ 


, 0L 


/* -first character 

*/ 


, 256L 


/* -count 

*/ 


, alWidthTable 

/* -returned width table 

*/ 


); 


if (fRet) /* query font metrics */ 
fRet = GpiQueryFontMetrics( hps /* -PS handle */ 

, (LONG)sizeof(FONTMETRICS)/* -metrics length */ 
, &fmMetrics /* -returned metrics */ 
); 


Figure 4.2 KemCharString Function. 
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if (fRet && fmMetrics.sKerningPairs!=0) 

/* if kerning pairs exist 

*/ 

{ 

/* allocate memory for 

*/ 


/* kerning pai rs 

*/ 

akrnprs = mal1oc(fmMetrics.sKerningPairs*sizeof 
fRet = (akrnprs!=NULL); 

(KERN INGPAIRS)); 


if (fRet) 

/* query Kerning pairs 

*/ 

fRet = GpiQueryKerningPairs( hps 

/* -PS handle 

*/ 

, fmMetrics.sKerningPairs /* -count 

*/ 

, akrnprs 

/* -returned Kern pairs 

*/ 

) != GPI ALTERROR; 

} 


if (fRet) 

/ 



i 

for (i=0 ;i<1 count; i++ ) 

/* assemble character 

*/ 

alWidths[i] = alWidthTableCpchString[i ] ]; 

/* string width array 

*/ 

for (i =0 ; id count-1; i++ ) 

/* for each character 

*/ 

{ 

/* pair in the string 

*/ 

for (j=0 ;j<fmMetrics.sKerningPairs; j++ ) 

/* search for matching 

*/ 

{ 

/* kerning pair 

*/ 


if ( pchString[i] = (UCHAR)akrnprs[j].sFi rstChar &&/* if matching */ 
pchString[i+l] = (UCHAR)akrnprs[j].sSecondChar/* kerning pair */ 
) /* found */ 

{ 


alWidths[i] += akrnprs[j].sKerningAmount; 
break; 



/* adjust width*/ 
/* and break */ 



/* draw the character 

*./ 


/* using character string 

*/ 


/* width array 

*/ 

fRet = (BOOL)GpiCharStringPos( hps 

/* -PS handle 

*/ 

, NULL 

/* -rectangle 

*/ 

, CHS_VECT0R 

/* -options 

*/ 

, ICount 

/* -count 

*/ 

, pchString 

/* -character string 

*/ 

, a 1 Widths 

/* -width array 

*/ 


); 


) 


free(alWidths ); 

/* 

free 

memory 

*/ 

free(akrnprs ); 

/* 

free 

memory 

*/ 

free(alWidthTable ) ; 

/* 

free 

memory 

*/ 


return(fRet) ; 

} 


Figure 4.2 (continued) 


assembled from the width table information and each pair of characters is com¬ 
pared for a match against each kerning pair. If a match is found then the kerning 
value is used to adjust the corresponding character width (for the first character 
of the pair). The character string is displayed using GpiCharStringPos with the 
character width array used as a vector of increment values. Clearly, if this function 
were to be used multiple times for the same font then performance would be 
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improved by providing the width table and kerning pair arrays as parameters 
rather than querying these for every character string. Also, the kerning pairs are 
returned in order of codepoint and a binary search could therefore be used to 
improve performance. 

Support for Adobe Type 1 Fonts requires no change to an application which 
supports the earlier OS/2 outline fonts. 


FOOT METRICS 

Font terminology is derived from old fashioned printing technology giving rise to 
terms such as leading (pronounced ledding) from the use of metallic lead in early 
printing. 

Fonts are described by a collection of metrics contained in the fields of a 
FONTMETRICS structure as follows: 

szF amilyname; 

szFacename; 

idRegistry; 

usCodePage; 

lEmHeight; 

IXHeight; 

IMaxAscender; 

IMaxDescender; 

ILowerCase Ascent; 

ILowerCaseDescent; 

1 InternalLe a ding; 

lExtemalLeading; 

lAveCharWidth; 

IMaxCharlnc; 

lEmlnc; 

IMaxBaselineExt; 

sCharSlope; 

slnlineDir; 

sCharRot; 

usWeightClass; 
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usWidthClass; 

sXBeviceRes; 

sYDeviceRes; 

sFirstChar; 

sLastChar; 

sDefaultChar; 

sBreakChar; 

sNominalPointSize; 

sMinimumPoint S ize; 

sMaximumPointSize; 

fsType; 

fsDefn; 

fs Selection; 

fsCapabilities; 

lSubscriptXSize; 

lSubscriptYSize; 

lSubscriptXOffset; 

ISubscriptYOffset; 

lSuperscriptXSize; 

ISuperscriptYSize; 

lSuperscriptXOffset; 

ISuperscriptYOffset; 

HJnderscoreSize; 

lUnderscorePosition; 

IStrikeoutSize; 

IStrikeoutPosition; 
sKerningPairs; 
sFamilyClass; and 
IMatch. 

The font metrics can be queried for all available fonts using GpiQueryFonts and, 

for the currently selected font, using GpiQueryFontMetrics. The FONTMETRICS 
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structure includes szFamilyname (Family name) szFacename (typefac 
sNominalPointSize, (point size) usCodePage (code page), fsDefn flags specifying 
whether or not the font type is outline (FM_DEFN_OUTLINE) or raster, and a 
number of important dimensions, some of which are illustrated in Figure 4-3. 

Font selection is normally performed using szFacename, the outline/raster flag 
(FM_DEFN_OUTLINE), and, for raster fonts only, sNominalPointSize, 
sXDeviceRes, and sYDeviceRes (the latter defining the horizontal and vertical 
device resolution for which the font was designed). szFamilyname is a more 
general name than szFacename and can be used for font matching when a font 
with the exact szFacename required is not available. A font, for example, with 
szFacename of “Courier Bold Italic” will have an szFamilyname of “Courier”. 

The metrics IMaxCharInc and lAveCharWidth are useful for horizontal charac¬ 
ter positioning and determining the average and maximum widths of a text field. 
The vertical spacing required for rows of text can be determined by 
IMaxBaselineExt+lExtemalLeading but this is not always ideal, as it may produce 
different results with different fonts of the same point size. lEmHeight*1.2 is an 
alternative method that is sometimes preferred. lExtemalLeading (which is often 


7K- Tf 



IMaxCharInc lAveCharWidth lExtemalLeading 



Figure 4.3 Important Font Dimensions (monospaced font). 
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zero) is the maximum recommended inter-row spacing that can be added to 
IMaxBaselineExt without affecting the pleasing appearance of the text, and can 
be reduced as required. The top row of text should be positioned at least 
IMaxAscender+lExtemalLeading below the top of the output area. Note that 
IMaxBaselineExt is equal to the sum of IMaxAscender and IMaxDescender. 

Two other important metrics are lEmHeight and lEmlnc that together define the 
Em Square. The Em Square is often viewed as representing the size of the letter ‘M’ 
but this is incorrect. The lEmHeight metric, in fact, represents the font point size 
converted (from device space) into world coordinates and the sum of lE mH eight plus 
llnternalLeading is also equal to IMaxBaselineExt. As stated earlier, font point size 
is not precisely defined in terms of any measurable characteristic of the visible 
characters and neither, therefore, are lEmHeight and lEmlnc. 

For outline fonts, lEmHeight and lEmlnc are set to the character box attribute 
dimensions and can therefore be controlled directly using GpiSetCharBox and 
GpiSetAttrs. Other width and height metrics such as lAveCharWidth and 
IMaxBaselineExt are scaled in the same proportion. Clearly, character width will 
vary as the character box attribute changes, however, the ratio CharacterWidth 
/lEmlnc is normally constant for a given character of a particular font or, for a 
non-proportional font, for all characters in the font (i.e., lAveCharWidth/lEmlnc). 
The horizontal character spacing of outline characters (and raster characters 
drawn using character mode CM_MODE2) can therefore be determined by 
CharacterBox.cx*CharacterWidtb/lEmInc. 

The font metrics, when queried, are returned by the system in world coordi¬ 
nates. Therefore for raster font characters, these will vary each time there is any 
change to one of the GPI transform matrices. If IMaxBaselineExt and lAveChar 
Width are being used for raster font creation and there has been any transform 
change since the font metrics were last queried, then they must be queried again 
before being used as parameters to GpiCreateLogFont. Incorrect values will cause 
the font match to fail, the function will return FONT_DEFAULT instead of 
FONT_MATCH, and a default font (which may be an outline font) will be provided 
in place of that requested. 

Not all the FONTMETRICS fields are useful to an application. The sFirstChar 
and sLastChar fields, for example, define the total glyphs in a font rather than the 
subset available to a particular codepage. 


FONT SELECTION UNO LOGICAL FONT CREATION 

Font selection is performed by issuing GpiQueryFonts to query the metrics of the 
available fonts, searching the returned metrics for a suitable font and then issuing 
GpiCreateLogFont to create a logical font describing the required font. 
GpiCreateLogFont specifies an application defined identifier or set id (sometimes 
called an lcid), which is specified subsequently with GpiSetCharSet, 
GpiSetMarkerSet, GpiSetPatternSet, or GpiSetAttrs to select the font for draw¬ 
ing. A logical font is deleted using GpiDeleteSetld. 

Fonts are normally selected by Facename (szFacename) and, in the case of 
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raster fonts only, point size (outline font point size is controlled by the transforms 
and character box attribute). 

GpiQueryFonts can specify the required szFacenaxne value (or NULL if all 
available fonts are to be returned) and whether public (QF_PUBLIC) fonts, private 
(QF_PRIVATE) fonts, or both, are to be returned. 

Included in the FONTMETRICS information is a local font match number 
(IMatch) that, subject to certain limitations, can be used to simplify font selection 
by providing a 'quick and dirty* alternative method. The IMatch value and 
szFacename uniquely identify a font within the system and can be specified 
together on GpiCreateLogFont in place of the other metrics. The IMatch value 
should not, however, be used for font selection in the following situations: 

1. When the target PS is associated with a MetaFile DC (because the 
IMatch value will not be recorded in the MetaFile). 

2. When printing remotely on a network print server (IMatch value is 
unique only within the local system). 

3. In any situation where the IMatch value would need to remain valid 
after re-IPL (e.g., in a held print file). 

IMatch value is suitable for direct printing, local printing via the spooler that 
completes before re-IPL, or any queued printing using data type PM_Q_RAW. 

For raster fonts, the alternative method to specifying the IMatch value on 
GpiCreateLogFont is to specify IMaxBaselineExt and lAveCharWidth in addition 
to the required font szFacename. These must exactly match the values for the 
required font or the match will fail and a default font will be returned. If any 
transforms have changed since the font metrics were last queried, then the metrics 
must be queried again to obtain updated values as described above. Similarly, 
when printing via the spooler (i.e., with an OB_QUEUED DC) using data type 
PM_Q_STD, to minimize the risk of the font match failing on the print process, the 
DevOpenBC (DEVOPENDATA) pszQueueProcParams should specify real size 
(i.e., “XFM=0”) rather than default which is 'scale to fit/ 

For outline fonts, the match number buys little. It is sufficient to specify only 
szFacename together with the FATTR_FONTUSE_OUTLINE and/or 
FATTR_FONTU8E_TRANSFORMABLE fsFontUse flags on GpiCreateLogFont. 
As an outline font can be scaled at will, IMaxBaseLineExt and lAveCharWidth 
have little meaning and are ignored by the font matching algorithm. 

GpiCreateLogFont can also specify any combination of the following fsSelection 
indicators: 

FATTR_SEL_ITALIC; 

FATTR_SEL_UNDERSCORE; 

FATTR_SEL_STRIKEOUT; or 

FATTR_SEL_BOLB. 

These will cause the system to apply italic, underscore, strikeout, and bold 
simulations to non-device raster characters (and also outline font characters 



FONTS 


109 


although they are not really intended for, or ideal with the latter). These simula¬ 
tions are in addition to any (italic, etc.) characteristics included in the font design. 
These flags may not always be honored for device fonts. 

For outline font characters, the FATTRS_SEL_OUTLINE flag causes unfilled 
outline characters to be drawn (this was originally provided as a way of improving 
performance). 

When creating a raster font of specified point size, it is necessary to search the 
metrics of the available fonts for a raster font with the required point size that also 
matches the resolution of the target device. This is illustrated by the functions 
CreateRasterFont and CreateRasterFontJMatch in Figures 4-4 and 4-5. Note 
that the CAPS_HORIZONTAL_FONT_RES and CAPS_VERTICAL_FONT_RES 
values returned from DevQueryCaps are conveniently specified in pels per inch 
(unlike CAPS_HORIZONTAL_RESOLUTION and CAPS_VERTICAL_RESOLU¬ 
TION which are in pels per meter). A careful analysis of these values will reveal 
that for most displays, the resolution for font selection is higher than the true 
device resolution causing matching raster font characters to appear larger than 
expected. This is quite intentional and is based on the observation that the normal 
viewing distance for a display screen is significantly larger than that of printed 
output. It is therefore considered desirable for characters to appear larger on a 
display screen than when printed. 

This size difference is not necessarily ideal. It makes WYSIWYG between screen 
and printer difficult with raster fonts. Also, if, for example, GpiQueryCharStringPos 
is used for raster font character positioning when creating a MetaFile for 
subsequent printing, the position values obtained and recorded in the MetaFile 
will be incorrect for the printer, even for a printer font with a matching Facename 
and point size. This is because a MetaFile assumes compatibility with the display 
and the MetaFile and printer font sizes will be different. To overcome this, a 
separate PS associated with a printer DC and a separate printer font must be used 
for determining the character positions recorded in the MetaFile. 

The function CreateOutlineFont in Figure 4-6 illustrates outline font creation 
and the function AllocateSetID in Figure 4-7 illustrates the use of 
GpiQueryNumberSetlds and GpiQuerySetlds to determine the set ids already in 
use and to allocate an unused value. 

When selecting a font, it is often desirable for performance reasons (and appear¬ 
ance) to select a device rather than a generic font. This can be established by 
examining either the fsDefn flags or the IMatch value in the FONTMETRICS. For 
a device font, the FMJDEFN_GENERIC flag is not set and the IMatch value is 
negative (I have found that, for some drivers, the IMatch approach seems slightly 
more reliable). 


OUTLINE font scaling using character box attribute 

Outline fonts are designed in a notional font definition space above world coordi¬ 
nate space (see Figure 7-1). The dimensions of this space, which is normally a 
1000x1000 square, are returned as the sXDeviceRes and sYDeviceRes 
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FONTMETRICS fields and these particular metrics are unaffected by the trans¬ 
forms and character box attribute. The transform from font definition space to 
world coordinate space is defined by the ratio of the sXDeviceRes and 
sYDeviceRes rectangle in font definition space and the character box attribute 
rectangle in world coordinate space. For an outline font, the character box 
attribute is, in fact, the same as the Em Square. As mentioned earlier, it is the 
Em Square dimensions lEmHeight and lEmlnc that are set by the character box 
attribute height and width values (for an outline font). It is therefore possible for 
lAveCharWidth and IMaxBaseLineExt to exceed the character box dimensions 
and for these to differ between fonts of different design, even though the character 
box attribute dimensions may be identical. The effect of the character box attri¬ 
bute on horizontal spacing of outline and CM_MODE2 raster font characters was 
described earlier. 

The function SetOutlineFontPointSize in Figure 4-8 illustrates how to scale an 
outline font to a specified point size. Note that the lEmHeight metric is a measure 
of font point size in world coordinates and, for an outline font, is equal to the height 
of the character box attribute. The required point size is achieved by determining 
the size in pels of the required font point size, converting this to world coordinates 
to provide the required lEmHeight value and specifying this value as the character 
box attribute dimensions. 

The function ScaleOutlineToFixed in Figure 4-9 illustrates how to scale an 
outline font size to match that of a specified raster font. Note that this is achieved 
by using the character box attribute to set the outline font lEmHeight value to 
match that of the raster font. Any remaining size differences between outline and 
raster font characters (even with the same szFacename) are due to differences in 
font design. Alternative scaling algorithms can use different metrics such as 
IXHeight (and can give better results). This is illustrated by the function 
ScaleOutlineToFixed2 in Figure 4-10. This queries the metrics of the raster font 
and then sets the character box attribute to a known value of 1000x1000 before 
querying the metrics of the outline font. The character box attribute is then scaled 
by the amount (i.e., Raster_lXHeighi/Outline_lXHeight) required to set the outline 
IXHeight to a value that matches the raster font. 

A similar approach is used to set the horizontal pitch of a font to a specified value 
in characters per inch, as illustrated by the function SetHorizontalPitch in Figure 
4-11. Here the character box attribute is again set to a known value of 1000x1000 
before querying the metrics of the outline font. The character box attribute is then 
scaled by the value (i.e., Required_lAveCharWidtb/01d_lAveCharWidth) required 
to set the pitch to the specified value (where Required_lAveCharWidth in pels is 
determined from IXResolutiou/pitch). Note that average character width must be 
converted from world to device coordinates using GpiConvert. 

As mentioned above, outline fonts are normally defined in a 1000x1000 square 
definition space. The major exceptions to this are built in device outline fonts such 
as those provided by a plotter. To obtain ideally (i.e., as designed) outline font 
characters, the aspect ratio of the character box attribute should match that of the 
sXDeviceRes and sYDeviceRes font metric dimensions (for an isotropic coordinate 
system). 
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GPS AND FONT CODEPAGES 

The system default codepage is the first codepage specified in the CODEPAGE 
command of CONFIG.SYS, or is codepage 850 if CONFIG.SYS contains no 
CODEPAGE command. (Note that DosSetCp cannot be used in a Presentation 
Manager application but both DosSetProcCp and the CHCP command can be used 
to switch between the two codepages specified in CONFIG.SYS). The GPI Presen¬ 
tation Space codepage is used for displaying GPI font characters and this will 
default to the process codepage that will be either the system default or some other 
value set by DosSetProcCp or CHCP. 

Regardless of the values specified in the CONFIG.SYS CODEPAGE command, 
a GPI PS codepage can be set to any of the following values using GpiSetCp: 


ASCII US ENGLISH 

437 


ASCII MULTILINGUAL 

850 


ASCII PORTUGUESE 

860 


ASCII CANADIAN FRENCH 

863 


ASCII NORWEGIAN 

865 


ASCII DESKTOP PUBLISHING 

1004 


EBCDIC US ENGLISH 

37 


EBCDIC AUSTRIAN GERMAN 

273 


EBCDIC BELGIAN 

500 


EBCDIC DANISH NORWEGIAN 

277 


EBCDIC FINNISH SWEDISH 

278 


EBCDIC ITALIAN 

280 


EBCDIC PORTUGUESE 

37 


EBCDIC SPANISH 

284 


EBCDIC UK ENGLISH 

285 


EBCDIC FRENCH 

297 


EBCDIC INTERNATIONAL 

500 


EBCDIC BELGIAN (M) 

274 

supported for migration 
purposes 

EBCDIC PORTUGUESE (M) 

282 

supported for migration 
purposes 


The GPI PS codepage can be queried using GpiQueryCp. 

System font files are designed to provide a universal character set that includes 
all characters required by all of the above codepages, and to provide the necessary 
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codepoint to character mappings required by each codepage. For a font that 
supports all of the above codepages, GpiQueryFonts will return a value of zero in 
the FONTMETRICS usCodePage field, whereas for a font that supports only a 
single codepage this non-zero codepage value will be returned. 

When creating a logical font using GpiCreateLogFont, the codepage can be 
defaulted by specifying zero in the usCodePage field of the FATTRS structure. It 
is normally safer, however, to specify the codepage explicitly (e.g., by using the 
current GPI codepage value as shown in the CreateRasterFont example). 

BITMAP SET IDS 

In addition to its use for specifying a logical font as a character, pattern, or marker 
set as described above, a set id can also be used to define a bitmap as an area fill 
pattern. To use a bitmap for area fill, the bitmap must be tagged with a set id using 
GpiSetBitmapId. The bitmap can then be selected as the current area fill pattern 
using GpiSetPatternSet or GpiSetAttrs in the normal way. Note that 
GpiSetPattern is not required as this attribute is ignored for bitmaps. A bitmap 
set id is deleted using GpiDeleteSetld. 

Note that a bitmap may be simplified when used as an area fill pattern, for 
example, it will be converted to monochrome and only part of a large bitmap (e.g., 
an 8x8 pel rectangle) might be used. 


/* crasfont.c */ 


LONG CreateRasterFont (HPS hps) 

{ 

/* Create a logical font for a 12 point public Courier raster font without */ 
/* using IMatch and return the set id (or GPI_ERR0R for error). */ 

/* */ 

/* inputs: hps PS handle */ 

/* */ 

/* returns: LONG Set ID (Lcid) of the newly created font (or GPI_ERR0R) */ 

/* */ 


^define 

POINTSIZE 120 




#define 

FACENAME “Courier” 




#define 

FONTNAME “F0NT01" 




PFONTMETRICS afmMetrics = NULL ; 

/* 

pointer to FONTMETRICS array 

*/ 

LONG 

1NumFonts 

/* 

number of fonts available 

*/ 

LONG 

1RemFonts = GPI_ALTERROR 

/* 

number fonts not returned 

*/ 

LONG 

1ReqFonts 

/* 

number fonts requested 

*/ 

LONG 

1XDevRes 

/* 

actual X device resolution 

*/ 

LONG 

1YDevRes 

/* 

actual Y device resolution 

*/ 

BOOL 

fRet = FALSE 

/* 

BOOL return code 

*/ 

HDC 

hdc = NULL 

/* 

DC handle 

*/ 

LONG 

1 Leid = GPI_ERR0R 

/* 

set id 

*/ 

INT 

i 

/* 

array index 

*/ 

USHORT 

usCodepage = GPI_ERR0R 

/* 

codepage 

*/ 

FATTRS 

fatAttrs 

/* 

font attributes 

*/ 


Figure 4.4 CreateRasterFont Function. 
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/**************************************************************************** i 


/* * / 

/* Query the number of fonts to determine how much memory to allocate for */ 

/* font metrics, allocate the memory and query the metrics for all public */ 

/* fonts with the matching facename. */ 

/* */ 


/****************************************************************************/ 


1ReqFonts = OL; 


INumFonts = GpiQueryFonts( hps 

/* Query Number of Fonts 

*/ 

/* -PS handle 

*/ 

, QF PUBLIC 

/* -options 

*/ 

, FACENAME 

/* -facename 

*/ 

, &1ReqFonts 

/* -number of fonts 

*/ 

, OL 

/* -metrics length 

*/ 

, NULL 
); 

/* -returned metrics 

*/ 

if ((1 NumFonts!=GPI_ALTERROR)&&(1NumFonts!= OL)) 

/* allocate memory for 

*/ 

afmMetrics = mal1oc((SHORT)(1NumFonts*sizeof(FONTMETRICS))); /* metrics 

*/ 

if (afmMetrics != NULL) 

/* query Font Metrics 

*/ 

1RemFonts = GpiQuery Fonts( hps 

/* -PS handle 

*/ 

, Q F_P U B LIC 

/* -options 

*/ 

, FACENAME 

/* -facename 

*/ 

, &1NumFonts 

/* -number of fonts 

*/ 

, (LONG)sizeof(FONTMETRICS) /* -metrics length 

*/ 

, afmMetrics 

/* -returned metrics 

*/ 


/**************************************************************************** 

/* . */ 
/* Query the actual horizontal and vertical resolution for the device. */ 

/* */ 
/**************************************************************************** 


if (1RemFonts != GPI_ALTERROR) 

hdc = GpiQueryDevice(hps); /* query associated DC handle */ 

if ((hdc!=NULL)&&(hdc!=HDC_ERROR)) /* query actual device X res */ 

fRet = DevQueryCaps( hdc /* -DC handle */ 

, CAPS_H0RIZ0NTAL_F0NT_RES /* -first item requested */ 

/* -number of caps requested */ 
/* -returned caps */ 


/* query actual device Y res */ 
/* - DC handle */ 

, CAPS_VERTICAL_FONT_RES /* -first item requested */ 

» /* -number of caps requested */ 

» &!YDevRes /* -returned caps */ 


JLL 

&1XDevRes 


); 

if (fRet) 

fRet = DevQueryCaps( hdc 


Figure 4.4 ( continued ) 
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/* 


*/ 


/* Search the font metrics for a font that satisfies all of the following */ 
/* conditions and create a logical font for it without using IMatch: */ 
/* font is raster */ 
/* facename matches required facename */ 
/* font device resolution matches actual device resolution horizontally */ 
/* font device resolution matches actual device resolution vertically */ 
/* */ 


if (fRet) 

{ /* step through and examine */ 

for (i = 0; i < (I NT)1NumFonts; i++) /* metrics for each font */ 


if (!(afmMetrics[i].fsDefn & FM_DEFN_OUTLINE) /* check for raster */ 
&& !(strcmp(afmMetrics[i].szFacename, FACENAME)) /* compare facename */ 


&& (afmMetrics[i].sNominalPointSize 
&& ((LONG)afmMetrics[i].sXDeviceRes 
&& ((LONG)afmMetrics[i].sYDeviceRes 
{ 

ILcid = A11ocateSetlD(hps); 

if (1 Leid1=GPI_ERR0R) 

usCodepage = GpiQueryCp(hps ) ; 


= POINTSIZE)/* 

compare point size 

*/ 

== 1XDevRes) /* 

compare X and Y Res 

*/ 

== 1YDevRes))/* 

for this device 

*/ 

/* 

get a set id 

*/ 

/* 

query PS codepage 

*/ 

/* 

-ps handle 

*/ 


/* set font attributes */ 


fatAttrs.usRecordLength = sizeof(FATTRS); /* -record length */ 
fatAttrs.fsSelection = 0; /* -selection flags */ 
fatAttrs.1 Match = 0L; /* -match value */ 
strepy(fatAttrs.szFacename, afmMetrics[i].szFacename); /* -facename */ 
fatAttrs.idRegistry = afmMetrics[i].idRegistry; /* -registry id */ 
fatAttrs.usCodePage = usCodepage; /* -codepage */ 
fatAttrs.1MaxBaselineExt = afmMetrics[i].1MaxBaselineExt;/* -max ble */ 
fatAttrs.1AveCharWidth = afmMetrics[i].1AveCharWidth ; /* -ave chw */ 
fatAttrs.fsType = 0; /* -type flags */ 
fatAttrs.fsFontUse = 0; /* -font use flags */ 


if (usCodepage!=GPI_ERR0R) 
fRet = GpiCreateLogFont( hps 

, (PSTR8)FONTNAME 
, ILcid 
, &fatAttrs 
) != GPI_ERR0R; 

break; 

} 

} 

} 



/* create logical font */ 


/* -PS handle */ 
/* -font name */ 
/* -set id */ 
/* -font attributes */ 


free(afmMetrics ) ; 

if (!fRet || usCodepage==GPI_ERROR) 
1 Leid = GPI_ERR0R; 

retu rn (1 Leid ) ; 


Figure 4.4 (continued) 
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/* 

LONG CreateRasterFont_lMatchCHPS hps) 
Create 


crfmatch.c */ 


a logical font for a 12 point public Courier raster font using 
1 Match and return the set id (or GPI_ERR0R for error). 


/ 

/ 

/ 

/ 

/ 

/* returns 
/* 


inputs: 


hps PS handle 

LONG Set ID (Leid) of the newly created font (or GPI_ERR0R) 


pointer to FONTMETRICS array 
number of fonts available 


#define POINTSIZE 120 
^define FACENAME “Courier” 

#define FONTNAME “F0NT01" 

PFONTMETRICS afmMetrics = NULL 

/* 

LONG 

1 NumFonts 

/* 

LONG 

1 RemFonts = GPI_ALTERR0R 

/* 

LONG 

1ReqFonts 

/* 

LONG 

1XDevRes 

/* 

LONG 

1YDevRes 

/* 

BOOL 

fRet = FALSE 

/* 

HDC 

hdc = NULL 

/* 

LONG 

1 Lei d = GPI.ERROR 

/* 

INT 

i 

/* 

USHORT 

usCodepage = GPI_ERR0R 

/* 

FATTRS 

fatAttrs 

/* 


number fonts requested 
actual X device resolution 
actual Y device resolution 
BOOL return code 
DC handle 


codepage 
font attributes 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


/**************************************************************************** 

/* */ 
/* Query the number of fonts to determine how much memory to allocate for 
/* font metrics, allocate the memory and query the metrics for all public 
/* fonts with the matching facename. 


/* 


*/ 

/ 

/ 

/ 


/****************************************************************************^ 
1ReqFonts = OL; 


INumFonts = GpiQueryFonts( hps 

, QF_PUBLIC 
, FACENAME 
, &1ReqFonts 
, OL 
, NULL 
); 


/* Query Number of Fonts */ 


/* -PS handle 
/* -options 
/* -facename 
/* -number of fonts 
/* -metrics length 
/* -returned metrics 


if ((INumFonts! GPI_ALTERROR)&&(1NumFonts!— OL)) /* allocate memory for 
afmMetrics = mal1oc((SHORT)(1NumFonts*sizeof(FONTMETRICS))); /* metrics 


if (afmMetrics != NULL) 

1RemFonts = GpiQueryFonts( hps 

, QF_PUBLIC 

, FACENAME 
, &1NumFonts 


/* query Font Metrics 
/* -PS handle 
/* -options 
/* -facename 
/* -number of fonts 


); 


(L0NG)sizeof(FONTMETRICS ) /* -metrics length 
afmMetrics /* -returned metrics 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


/* */ 
I * the actual horizontal and vertical resolution for the device. */ 

/****************************+***************i'* i < i '* i ' i , i ' i ' i ' i ' i ' i ' i ' i 'i'* i ' il i' i , i , i , i!ti , i ' i '+ i ' i ''i / / 

if (1 RemFonts != GPI_ALTERROR) 

hdc = GpiQueryDevice(hps); /* query associated DC handle */ 

if ((h d c!= NU L L) M( hdc !=HD c _E R R° R)) /* query actual device X res */ 

fRet = DevQueryCapst hdc /* -DC handle */ 

, CAPS_HORIZONTAL_FONT_RES /* -first item requested */ 
’ JL „ /* -number of caps requested */ 

, &lXDevRes /* -returned caps */ 


Figure 4.5 CreateRasterFontJMatch Function. 
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if (fRet) /* query actual device Y res */ 

fRet = DevQueryCapsC hdc /* -DC handle */ 

, CAPS_VERTICAL_FONT_RES /* -first item requested */ 
, 1L /* -number of caps requested */ 

, &!YDevRes /* -returned caps */ 

/************************************************************* 

/* */ 

/* Search the font metrics for a font that satisfies all of the following */ 
/* conditions and create a logical font for it using IMatch: */ 

/* font is raster */ 

/* facename matches required facename */ 

/* font device resolution matches actual device resolution horizontally */ 
/* font device resolution matches actual device resolution vertically */ 
/* */ 

/****************************************************** 

if (fRet) 

{ /* step through and examine */ 

for (i = 0; i < (I NT)1NumFonts; i++) /* metrics for each font */ 

{ 

if (!(afmMetrics[i].fsDefn & FM_DEFN_OUTLINE) /* check for raster */ 

&& !(strcmpCafmMetrics[i].szFacename, FACENAME)) /* compare facename */ 
&& (afmMetrics[i].sNominalPointSize == POINTSIZE)/* compare point size */ 
&& ((L0NG)afmMetrics[i].sXDeviceRes == lXDevRes) /* compare X and Y Res */ 
&& ((L0NG)afmMetrics[i].sYDeviceRes == 1YDevRes))/* for this device */ 
{ 

ILcid = AllocateSetlD(hps); /* get a set id */ 

if (1 Leid!=GPI_ERR0R) /* query PS codepage */ 

usCodepage = GpiQueryCp(hps); /* -ps handle */ 

/* set font attributes */ 
fatAttrs.usRecordLength = sizeof(FATTRS); /* -record length */ 

fatAttrs.fsSelection = 0; /* -selection flags */ 

fatAttrs.1 Match = afmMetrics[i].1 Match;/* -match value */ 

strcpy(fatAttrs.szFacename, afmMetrics[i].szFacename); /* -facename */ 
fatAttrs.idRegistry = afmMetrics[i].idRegistry; /* -registry id */ 
fatAttrs.usCodePage = usCodepage; /* -codepage */ 

fatAttrs.1MaxBaselineExt = 0L; /* -max ble */ 

fatAttrs.1AveCharWidth = 0L; /* -ave chw */ 

fatAttrs.fsType = 0; /* -type flags */ 

fatAttrs.fsFontUse = 0; /* -font use flags */ 


if (usCodepage!=GPI_ERR0R) 
fRet = GpiCreateLogFont( hps 

, (PSTR8)FONTNAME 
, ILcid 
, &fatAttrs 
) != GPI_ERR0R; 

break; 

} 

} 

} 


/* */ 

/* Free the memory. */ 

/* If error set returned lcid to GPI_ERR0R. */ 

/* */ 


/*★★★*★★*★***★★★★***★★★********★**********★**★****★*★**★***★★★**■*:•*■**★★★**★*★•*■/ 
free(afmMetrics); 

if (ifRet II usCodepage==GPI_ERROR) 

ILcid = G PI_E RRO R; 

return (ILcid); 


/* create logical font */ 


/* -PS handle */ 
/* -font name */ 
/* -set id */ 
/* -font attributes */ 


Figure 4.5 (continued) 
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/* crtolfnt.c */ 

LONG CreateOutlineFont (HPS hps) 

{ 

/* Create a logical font for a Courier Bold outline font without */ 

/* using IMatch and return the set id. */ 

/* */ 

/* inputs: hps PS handle */ 

/* */ 

/* returns: LONG Set ID (Leid) of the newly created font */ 

/* or GPI_ERR0R for error or not found */ 


^define FACENAMEB “Courier Bold" 

#define FONTNAME “F0NT01" 


PFONTMETRICS 

afmMetrics = NULL 

/* 

pointer to FONTMETRICS array 

*/ 

LONG 

1NumFonts 

/* 

number of fonts 

*/ 

LONG 

1ReqFonts 

/* 

number fonts requested 

*/ 

LONG 

1RemFonts = GPI ALTERROR 

/* 

number fonts not returned 

*/ 

BOOL 

fRet = FALSE 

/* 

BOOL return code 

*/ 

HDC 

hdc = NULL 

/* 

DC handle 

*/ 

LONG 

1 Leid = GPI_ERR0R 

/* 

set id 

*/ 

INT 

i 

/* 

array index 

*/ 

USHORT 

usCodepage = GPI_ERR0R 

/* 

codepage 

*/ 

FATTRS 

fatAttrs 

/* 

font attributes 

*/ 


/************************************************************^ 

/* */ 

/* Query the number of fonts to determine how much memory to allocate for */ 

/* font metrics, allocate the memory and query the metrics for all public */ 

/* fonts with the required facename. */ 

/* */ 

/****************************************************************************/ 


1ReqFonts = OL; 

/* 

Query Number of Fonts 

*/ 

1NumFonts = GpiQueryFonts( hps 

/* 

-PS handle 

*/ 

, QF PUBLIC 

/* 

- options 

*/ 

, FACENAMEB 

/* 

-facename 

*/ 

, &1ReqFonts 

/* 

-number of fonts 

*/ 

, OL 

/* 

-metrics length 

*/ 

, NULL 
); 

/* 

-returned metrics 

*/ 

if ((1NumFontsI=GPI_ALTERROR)&&(1NumFonts!= OL)) 

/* 

allocate memory for 

*/ 

afmMetrics - malloc((SHORT)(1NumFonts*sizeof(FONTMETRICS))); /* metrics 

*/ 


if (afmMetrics != NULL) 

/* query Font Metrics 

*/ 

1RemFonts = GpiQueryFonts( hps 

/* -PS handle 

*/ 

, QF PUBLIC 

/* -options 

*/ 

, FACENAMEB 

/* -facename 

*/ 

, &1NumFonts 

/* -number of fonts 

*/ 

, (LONG)sizeof(FONTMETRICS) /* -metrics length 

*/ 

, afmMetrics 

/* -returned metrics 

*/ 


Figure 4.6 CreateOutlineFont Function. 
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/* 


* / 


/* Search the font metrics for a font that satisfies the following */ 
/* conditions and create a logical font for it without using IMatch: */ 
/* font is outline */ 
/* facename matches required facename */ 
/* */ 


if (1RemFonts != GPI_ALTERROR) 

{ /* step through and examine */ 

for (i - 0; i < (INT)1NumFonts; i++) /* metrics of each font */ 

{ 

if ((afmMetrics[i].fsDefn & FM_DEFN_0UTLINE) /* check for outline */ 

&& !(strcmp(afmMetrics[i].szFacename, FACENAMEB)))/* compare facename */ 

{ 

ILcid = A11ocateSetID(hps); /* get a set id */ 

if (1 Leid!=GPI_ERR0R) /* query PS codepage */ 

usCodepage = GpiQueryCp(hps ); /* -ps handle */ 

/* set font attributes */ 
fatAttrs.usRecordLength = sizeof(FATTRS); /* -record length */ 

fatAttrs.fsSelection = 0; /* -selection flags */ 

fatAttrs.IMatch = 0L; /* -match value */ 

strepy(fatAttrs.szFacename, afmMetrics[i].szFacename); /* -facename */ 
fatAttrs.idRegistry = afmMetrics[i].idRegistry; /* -registry id */ 

fatAttrs.usCodePage = usCodepage; /* -codepage */ 

fatAttrs.1MaxBaselineExt = 0L; /* -max ble */ 

fatAttrs.1AveCharWidth = 0L; /* -ave chw */ 

fatAttrs.fsType = 0; /* -type flags */ 

fatAttrs.fsFontUse = ( FATTR_F0NTUSE_0UTLINE /* -font use flags */ 

| FATTR_FONTUSE_TRANSFORMABLE); 


if (usCodepage!=GPI_ERR0R) 


/* 

create logical font 

*/ 

fRet = GpiCreateLogFont( 

hps 

/* 

-PS handle 

*/ 

f 

(PSTR8)FONTNAME 

/* 

-font name 

*/ 


1 Lei d 

/* 

-set id 

*/ 

) 

break; 

&fatAttrs 
!= GPI_ERR0R; 

/* 

-font attributes 

*/ 



free(afmMetrics ); 

if (!fRet || usCodepage==GPI_ERROR) 
1Lcid = GPI_ERR0R; 

return (1 Leid); 


Figure 4.6 (continued) 
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/* 


LONG A11ocateSetlD (HPS hps) 

{ 

/* Return an unused set id (Lcid) or GPI_ERR0R for 
/* 

/* inputs: hps PS handle 

/* 

/* returns: LONG unused set id (Lcid) 

/* 


al1ocset.c */ 


error (or none available). */ 

*/ 

*/ 

*/ 

*/' 

*/ 


^define MAXSETID 254L 


I NT 

i 


/* 

INT array index 

*/ 

LONG 

1 Lei d 

= GPI_ERR0R 

/* 

returned set id 

*/ 

LONG 

1 Count 


/* 

returned number of set ids 

*/ 

BOOL 

fRet 

= FALSE 

/* 

BOOL return code 

*/ 

PLONG 

alLcids 

= NULL 

/* 

returned set id pointer 

*/ 

PLONG 

alTypes 


/* 

returned type pointer 

*/ 

PSTR8 

aNames 


/* 

returned names pointer 

*/ 

1 Count 

= GpiQueryNumberSetlds(hps); /* 

query the number of set ids*/ 

if (lCount==0) 


/* 

if number set ids is zero 

*/ 

return(1L); 


/* 

set return set id to 1 

*/ 


if (1 Count!=GPI_ALTERROR) 

{ 

alLeids = mal1oc((SHORT)(16 * ICount)); /* allocate memory for */ 

alTypes = (PLONG)(alLeids + ICount); /* set ids, types and */ 

aNames = (PSTR8)(alTypes + ICount); /* names */ 

if (alLcids!=NULL) /* query set ids */ 

fRet = GpiQuerySetlds( hps /* -PS handle */ 

, ICount /* -number set ids queried */ 

, alTypes /* -returned types */ 

, aNames /* -returned names */ 

, alLcids /* -returned set ids */ 

); 

/* step through range of */ 

/* valid set ids searching */ 
if (fRet) /* returned set id array for */ 

{ /* an unused value */ 

for (1 Leid=l; 1 Leid<(MAXSETID+l); lLcid++) 

{ 

for (i=0; (i<(I NT)1 Count) && (alLcidsEi]1=1Lcid); i++); 


if (i==(I NT)1 Count) 
break; 


/* if unused value found */ 


if (1Lcid==MAXSETID+l) 
1Lcid = GPI_ERROR; 

} 

free(alLcids); 


return(1 Leid); 

} 


/* return the set id */ 


Figure 4.7 AllocateSetID Function. 
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/* setolpsz.c */ 

BOOL SetOutlineFontPointSize( HPS hps, LONG 1OutlineLcid) 

{ 

/* Set the character set to the specified outline font set id and set the */ 
/* character box attribute to give the outline font the required point size. */ 

/* Note that this function is intended to handle outline fonts designed in a */ 

/* square space with sXDeviceRes and sYDeviceRes equal (this is true for all */ 
/* Presentation Manager fonts that are not device fonts). */ 

/* */ 

/* inputs: hps PS handle */ 

/* lOutlineLcid Outline font set id */ 

/* */ 

//define POINTSIZE 10L 

//define POINTSPERINCH 72L 

HDC hdc ; /* DC handle */ 

BOOL fRet = FALSE ; /* BOOL return code */ 

LONG lYDevResFont ; /* vertical device resolution for font selection */ 

POINTL aptlPoints[2] ; /* point array */ 

SIZEF sizfxCharBox ; /* character box size */ 

LONG 1PointSizelnPels ; /* point size in pels */ 

LONG 1PointSizelnWC ; /* point size in world coordinates */ 


/* 

/* Query vertical device resolution for font selection. 
/* 


*/ 

*/ 

*/ 


hdc = GpiQueryDevice(hps ) ; 
if ((hdc != NULL) && (hdc != HDC_ERR0R)) 
fRet = DevQueryCaps( hdc 

, CAPS_VERTICAL_FONT_RES 
, 1L 

, &1YDevResFont 
); 


/* 

query the DC handle 

*/ 

/* 

query caps 

*/ 

/* 

-DC handle 

*/ 

/* 

-first item 

*/ 

/* 

-count of items 

*/ 

/* 

-returned resolution 

*/ 


/* 

/* Calculate required point size in pels rounded 
/* convert to world coordinates. 


up to the nearest pel and 


*/ 

*/ 

*/ 

*/ 


1PointSizelnPels = ((1YDevResFont*P0INTSIZE+(POINTSPERINCH/2))/POINTSPERINCH); 

aptlPoints[0].x = 0L; 
aptlPoints[0].y = 1L; 
aptlPoints[l].x = 0L; 
aptlPoints[1].y = 1PointSizelnPels+1; 


if (fRet) 


/* convert coordinates 

*/ 

fRet = GpiConvert( 

hps 

/* -PS handle 

*/ 

, 

CVTC DEVICE 

/* - source 

*/ 


CVTC WORLD 

/* -target 

*/ 


2L 

/* -count 

*/ 

, 

aptlPoints 

/* -coordinate array 

*/ 


); 

1PointSizelnWC = aptlPoints[l].y - aptlPoints[0].y; 


Figure 4.8 SetOutlineFontPointSize Function. 
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/****************************************************************************** J 
/* * / 
/* set the character set to the outline font set id */ 
/* set the character box dimensions to the point size in world coordinates */ 
/* converted to FIXED (i.e. times 0x10000). */ 
/* */ 


if (fRet) 

1* 

set char set 

*/ 

fRet = GpiSetCharSetC hps 

/* 

-PS handle 

*/ 

, 1OutlineLcid 
): 

/* 

-set id 

*/ 

sizfxCharBox.cx = 1PointSizeInWC*0xl0000; 
sizfxCharBox.cy = 1PointSizeInWC*0xl0000; 




if (fRet) 

/* 

set char box 

*/ 

fRet = GpiSetCharBoxC hps 

/* 

-PS handle 

*/ 

, &sizfxCharBox 

/* 

-character box 

*/ 


); 


return(fRet); 

} 


Figure 4.8 (continued) 


/* sclolfx.c */ 

BOOL SealeOutlineToFixed (HPS hps, LONG 1OutlineLcid, LONG IRasterLcid) 

{ 


/* 

Set the character set to 

the specified outline 

font id and set the 

*/ 

/* 

character 

box attribute 

to give an outline font 

the same size as the 

*/ 

/* 

speci f i ed 

raster font (any remaining 

visual differences arise from 

*/ 

/* 

differences in font desi 

gn). 




*/ 

/* 







*/ 

/* 

inputs: 

hps 

PS handle 




*/ 

/* 


1 OutlineLcid 

Outline font 

set 

i d 


*/ 

/* 


1RasterLcid 

Raster font 

set 

i d 


*/ 

/* 







*/ 

BOOL 

fRet 




/* BOOL return code 

*/ 


F0NTMETRICS 

fmRMetrics 




/* raster font metrics 

*/ 

SIZEF 

sizfxCharBox 




/* character box size 

*/ 


/****************************************************************************** j 


/* */ 

/* set the character set to the raster font set id */ 

/* query the font metrics for the raster font */ 

/* set the character set to the outline font set id */ 

/* set the outline font character box attribute dimensions to the lEmHeight */ 
/* lEmlnc metric values for the raster font */ 

/* */ 


/************************* ★**★*****-*•★****•*:•*•-*■* ************7t******-!lf**Tlr*7k-********Tlr/ 

/* set raster font char set */ 

Figure 4.9 ScaleOutlineToFixed Function. 
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fRet = GpiSetCharSet( hps 


/* -PS handle 

*/ 

, IRasterLcid 
) ; 


/* -set id 

*/ 

if (fRet) 


/* query font metrics 

*/ 

fRet = GpiQueryFontMetrics( hps 


/* -PS handle 

*/ 

, (LONG)sizeofCFONTMETRICS) 

/* -metrics length 

*/ 

, &fmRMetrics 
); 


/* -returned metrics 

*/ 

if (fRet) 

/* set 

outline font char set 

*/ 

fRet = GpiSetCharSet( hps 


/* -PS handle 

*/ 

, lOutlineLcid 


/* -set id 

*/ 


); 


sizfxCharBox.cx = MAKEFIXED(fmRMetrics.1EmHeight,0); 
sizfxCharBox.cy = MAKEFIXED(fmRMetrics.1Emlnc,0); 


if (fRet) 

/* 

set char box 

*/ 

fRet = GpiSetCharBox( hps 

/* 

-PS handle 

*/ 

, &sizfxCharBox 

/* 

-char box size 

*/ 


return(fRet); 


Figure 4,9 (continued) 


sclolfx2.c */ 

BOOL SealeOutlineToFixed2( HPS hps, LONG 1OutlineLcid, LONG IRasterLcid) 


/* Set the character set to the specified outline font id and set the */ 
/* character box attribute to give an outline font the same size as the */ 
/* specified raster font. The character box is set to a value that scales */ 
/* the IXHeight metric of the outline font to match that of the raster */ 
/* font (any remaining visual differences arise from differences in font */ 
/* design ). */ 
/ * * / 
/* inputs: hps PS handle */ 
/* lOutlineLcid Outline font set id */ 
/* IRasterLcid Raster font set id */ 


BOOL fRet 

FONTMETRICS fmRMetrics 
FONTMETRICS fmOMetrics 
SIZEF sizfxCharBox 


/* BOOL return code */ 
/* raster font metrics */ 
/* outline font metrics */ 
/* character box size */ 



/* set the character set to the raster font set id */ 
/* query the font metrics for the raster font */ 
/* set the character set to the outline font set id */ 
/* set the character box attribute dimensions to a known value (1000x1000) */ 
/* query the font metrics for the outline font */ 
/* change character box dimensions to scale 1XHeight for the outline font to */ 
/* match that of the raster font and set the new character box attribute. */ 
/* */ 


Figure 4.10 ScaleOutlineToFixed2 Function. 
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/* set 

. raster font char set 

*/ 

fRet = GpiSetCharSet( hps 


/* -PS handle 

*/ 

, IRasterLcid 
); 


/* -set id 

*/ 

if (fRet) 


/* query font metrics 

*/ 

fRet = GpiQueryFontMetrics( hps 


/* -PS handle 

*/ 

, (LONG)sizeof(FONTMETRICS) 

/* -metrics length 

*/ 

, &fmRMetrics 
); 


/* -returned metrics 

*/ 

if (fRet) 

/* set 

outline font char set 

*/ 

fRet = GpiSetCharSet( hps 


/* -PS handle 

*/ 

, lOutlineLcid 
); 


/* -set id 

*/ 

sizfxCharBox.cx = 0x3E80000; 
sizfxCharBox.cy = 0x3E80000; 




if (fRet) 


/* set char box 

*/ 

fRet = GpiSetCharBox( hps 


/* -PS handle 

*/ 

, &sizfxCharBox 


/* -set id 

*/ 

); 

if (fRet) 


/* query font metrics 

*/ 

fRet = GpiQueryFontMetrics( hps 


/* -PS handle 

*/ 


, (LONG)sizeof(FONTMETRICS)/* -metrics length */ 
, &fmOMetrics /* -returned metrics */ 
); 


sizfxCharBox.cy = sizfxCharBox.cx 

= (0x03E80000/fm0Metrics.1XHeight)*fmRMetrics.1XHeight; 


if (fRet) 

/* 

set character box 

*/ 

fRet = GpiSetCharBox( hps 

/* 

-PS handle 

*/ 

, &sizfxCharBox 

/* 

-char box size 

*/ 


); 

return(fRet); 


Figure 4.10 (continued) 
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setpitch.c */ 


BOOL SetHorizontalPitch(HPS hps, LONG 1OutlineLcid, LONG 1 Pitch) 

{ 

/* Set the character set to the specified outline font id and set the */ 

/* character box attribute to provide the specified horizontal pitch in */ 

/* characters per inch. */ 

/* */ 

/* inputs: hps PS handle */ 

/* lOutlineLcid Outline font set id */ 

/* 1 Pitch required horizontal pitch in characters to inch */ 

/* */ 


BOOL fRet = FALSE 

FONTMETRICS fmOMetrics 
SIZEF sizfxCharBox 

LONG lXResolution 

LONG 1AveCharWidth 

POINTL aptlPoints[2] 

HDC hdc 


/* BOOL return code */ 
/* outline font metrics */ 
/* character box size */ 
/ * horizontal resolution */ 
/* average char width */ 
/* coordinate point */ 
/* DC handle */ 


/* */ 

/* query the device resolution */ 

/* set the character set to the outline font set id */ 

/* set the character box attribute dimensions to a known value (1000x1000) */ 

/* query the font metrics for the outline font */ 

/* convert the AveCharWidth to device coordinates (pels) */ 

/* calculate the new character box to give the required pitch */ 

/* NewBoxWidth = (01dBoxWidth/01dAveCharWidth)*XResolution/pitch */ 

/* where XResolution/pitch is equivalent to the new average character width */ 
/* The char box is thus scaled by the ratio NewAveCharWidth/01dAveCharWidth */ 
/* set the new character box attribute */ 

/* */ 



/* query the DC handle 

*/ 

hdc = GpiQueryDevice( hps ); 

/* -PS handle 

*/ 


if ((hdc! 

1=NULL)&&(hdc!=HDC_ERR0R)) 

/* 

query the resolution 

*/ 

fRet = 

DevQueryCaps( hdc 

/* 

-DC handle 

*/ 


, CAPS HORIZONTAL RESOLUTION 

/* 

-first item 

*/ 


, 1L 

/* 

- count 

*/ 


, &1XResolution 
); 

/* 

-returned resolution 

*/ 

lXResolution = 1XResolution*0xl0/0x276; 

/* 

convert from pel s per 



meter to pels per inch 

*/ 

if(fRet) 

/* 

set 

outline font char set 

*/ 

fRet = 

GpiSetCharSet( hps 

/ 

* -PS handle 

*/ 


, lOutlineLcid 

/ 

* -set id 

*/ 


); 


sizfxCharBox.cx = 0x3E80000; 
sizfxCharBox.cy = 0x3E80000; 


if (fRet) 

/* 

set 

char box 

*/ 

fRet = GpiSetCharBox( hps 

/* 

-PS 

handle 

*/ 

, &sizfxCharBox 

/* 

- set 

i d 

*/ 


); 


Figure 4.11 SetHorizontalPitch Function. 
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if (fRet) 

/* 

query font metrics 

*/ 

fRet = GpiQueryFontMetrics( hps 

/* 

-PS handle 

*/ 

, (LONG)sizeof(FONTMETRICS)/* -metrics length 

*/ 

, &fmOMetrics 
); 

/* 

-returned metrics 

*/ 

aptlPoints[0].x = 0L; 

/* 

convert average 

*/ 

aptlPoints[0],y = 0L; 

/* 

character width to 

*/ 

aptlPoints[1].x = fmOMetrics.1AveCharWidth; 

/* 

device coordinates 

*/ 

aptlPoints[1].y = 0L; 




if (fRet) 




fRet = GpiConvert( hps 

/* 

-PS handle 

*/ 

, CVTC WORLD 

/* 

-source 

*/ 

, CVTC DEVICE 

/* 

-target 

*/ 

. 2 L 

/* 

- count 

*/ 

, aptlPoints 

/* 

-array of points 

*/ 


); 

1AveCha rWi dth = aptl Poi nts[1].x - aptl Poi nts [0]. x ; 

/* scale character box to give the required pitch */ 

sizfxCharBox.cy = sizfxCharBox.cx 

= ((0x03E80000/lPitch)*lXResolution)/1AveCharWidth ; 


if (fRet) 


/* 

set character box 

*/ 

fRet = GpiSetCharBox( 

hps 

/* 

-PS handle 

*/ 

, 

&sizfxCharBox 

/* 

-char box size 

*/ 


); 


return(fRet); 

} 


Figure 4.11 (continued) 




Bitmaps 


A bitmap is a rectangular array of color or monochrome pixel data held in PC or 
device memory. It is used for the rapid transfer of rectangular blocks of pixel data 
between bitmaps and raster devices (or other bitmaps). Such operations are called 
Bit Block Transfer or BitBlt operations. 

Bitmaps are device dependent objects and every bitmap must at all times be 
owned by (and be compatible with) some device, although it is possible to change 
ownership of a bitmap to a different device. In order to perform a BitBlt operation, 
both the source and target of the BitBlt operation must be owned by the same 
device. 

See chapter 3 for a description of BitBlt drawing primitives. 


BITMAP FORMATS 

Bitmap formats are specified as the number of color planes and number of bits per 
pel. Standard bitmap formats are all defined with only a single plane and one or 
more bits per pel but this is only a convention. It is equally valid to describe the 
same bitmap as having one plane with eight bits per pel or eight planes with one 
bit per pel. The standard bitmap formats are as follows: 

• A single plane with 1 bit per pel (i.e., monochrome). 

• A single plane with 4 bits per pel (i.e., 16 color). 

• A single plane with 8 bits per pel (i.e., 256 color). 

• A single plane with 24 bits per pel (i.e., RGB). 

A presentation driver must allow bitmap creation in any of the four standard 
formats as well as in any non-standard internal device formats of its own. 
Although drivers must allow bitmap creation in the standard formats, it is not 
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essential for these formats to be supported internally. For formats not supported 
internally the driver will select its most appropriate internal device format and 
perform the necessary conversion of bitmap initialization data. In addition, all 
drivers must be capable of supporting bitmap data conversion between any of the 
standard formats and any internal device format. This is to allow bitmap data in 
any standard format to be transferred between application memory and a bitmap 
(in either direction) using GpiCreateBitmap, GpiSetBitmapsBits, and 
GpiQueryBitmapBits. 

Bitmap formats supported internally by a driver, where the first format re¬ 
turned is that which most closely matches the device, can be queried using: 

GpiQueryDeviceBitmapF ormats. 


The driver is entitled to modify bitmap initialization data in the process of 
converting it to internal format as follows: 

• Color table information provided (in a BXTMAPINFO structure) with 
bitmap initialization data on GpiCreateBitmap or GpiSetBitmapBits 
may be remapped to the nearest available device color. 

• Where the internal device bitmap format has fewer bits per pel 
than the data, loss of information may occur. For example, a 
monochrome printer will normally support only monochrome 
bitmaps internally and will therefore remap all colored bitmap data 
to black and white. 

• Where device background and foreground bitmap colors do not match 
the color table of the bitmap data, inversion of the bitmap bits and 
reversal of the color table may occur. This was a fairly serious 
problem when printing monochrome display bitmaps with some of 
the early printer drivers but the driver interface specification has 
since been clarified and the problem is now largely corrected for most 
drivers (at the time of writing a few inconsistencies remain, however, 
for bitmaps initialized by drawing to a monochrome printer bitmap 
and for transferring colored bitmaps from a color display to a mono¬ 
chrome printer). 


These effects will generally be apparent from an examination of BitBlt output or 
of the bitmap data returned from GpiQueryBitmapBits. 

Note that even where an application has not created its own logical color table, 
bitmaps are not restricted to the 16 colors in the standard color table but have 
access to the entire range of colors available in the device palette. Where 
GpiRealizeColorTable is supported and a realizable color table has been created, 
bitmaps have access to the full range of realized colors regardless of whether the 
color table is actually realized when the bitmap contents are initialized. These 
realized colors will, of course, only be displayed correctly if the target PS (of a 
BitBlt operation) has same color table that is also realized (see below). 
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BITMAP CREATION AND DELETION 


Bitmaps are created and deleted using the functions described below: 


GpsCreateBStmap 

This creates a new bitmap of specified dimensions and format and optionally 
initializes it. The bitmap dimensions (height, width) and format (planes, bits per 
pel) are specified in a BITMAPINFOHEADER structure parameter. The format of 
the bitmap initialization data may be different from that of the bitmap and is 
described by a separate BITMAPINFO structure parameter. The BITMAPINFO 
structure is the same as a BITMAPINFOHEADER structure except that for 
bitmap formats other than 24 bits per pel, it is followed by an array of color table 
information describing the color represented by each combination of bits. This 
color table will contain 2**n entries where n is the number of bits per pel. The 
length of the bitmap initialization data may exceed 64K bytes. 

For certain devices (e.g., 8514/A) bitmap creation in device internal format may be 
considerably faster if the bitmap color table exactly matches that of the device 
palette (this can be determined using GpiQueryRealColors). 


GpiLoadBitmap 

This creates and loads a bitmap from a resource file and returns the bitmap 
handle. The bitmap will typically have been originally created using the iconedit 
utility and compiled with the resource compiler. The rc file will typically contain a 
statement of the form: 

BITMAP ID_BITMAP3 mybmap.bmp 

where ID_BITMAP3 is a numeric constant (e.g., #define ID_BITMAP3 3) for the 
bitmap ID to be specified with GpiLoadBitmap, and mybmap.bmp is the name of 
the bitmap file created by iconedit. The compiled bitmap resource (res) file may be 
added to the application exe file using the resource compiler or included in a DLL 
resource file and loaded using DosLoadModule. 

GpiLoadBitmap specifies the height and width of the required bitmap and, 
where these differ from the values in the resource file, stretching or compression 
of the bitmap data will occur. Either or both dimensions may be specified as zero 
on GpiLoadBitmap causing the original value or values to be used unchanged (i.e., 
with no stretching or compression). 


WsnloadPointer 


This loads a pointer or icon (see below) from a DLL resource file and returns its 
handle. 



GpiDeleteBitmap 

This deletes the specified bitmap. 
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BITMAP SELECTION 

A bitmap may be used as the source or target of a BitBlt operation, or used as the 
target of any valid drawing operation. In order to draw to a bitmap, use it as the 
target of a GpiWCBitBlt operation, source, or target of GpiBitBlt, the bitmap must 
be selected into an OD_MEMORY DC associated with a PS. 

Also, in order to transfer bitmap ownership from one device to another, it must 
be deselected from the PS/DC for the old device (if selected) and then selected into 
a PS associated with an OD_MEMORY DC for the new device. This is accom¬ 
plished as follows: 

GpiSetBitmap(hps01d, NULL); /* deselect from existing PS 

(if selected) */ 

GpiSetBitmap(hpsNew, hbitmap); /* select to PS/OD_MEMORY 

DC for new device */ 

Note that GpiWCBitBlt does not require its source bitmap to be selected into a 
PS/DC, although it must be owned by the target device. If GpiSetBitmap is used 
to transfer bitmap ownership, the bitmap should then be deselected from the new 
device before GpiWCBitBlt is issued. Note also that bitmap ownership by a device 
will continue after the bitmap has been deselected from its PS/DC until it is 
selected to a PS/DC for a different device. 


BITMAP BATA FORMAT AND DATA TRANSFER 

Data can be transferred between a bitmap and application memory using: 
GpiSetBitmapBits; and 
GpiQueryBitmapBits. 

Both of these functions include a BITMAPINFO parameter. In the case of 
GpiSetBitmapBits, this specifies the size and format of the data to be transferred 
together with its color table. In the case of GpiQueryBitmapBits, only certain of 
the BITMAPINFO fields are required as inputs, the remainder being part of the 
returned data. The number planes and number of bits per pel (i.e., cPlanes and 
cBitCount) must be specified on input, whereas the height, width, and color table 
(i.e., cx, cy, and argbColor) are returned. In all cases involving the BITMAPINFO 
and BITMAPINFOHEADER structures, the length field (cbFix) should be initial¬ 
ized by the application. 

As mentioned earlier, the formats specified with these functions may differ from 
the actual bitmap format used internally and may also differ from the format 
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originally specified when the bitmap was created. Conversion is performed as 
necessary by the system. 

An example of the format of bitmap data and its BITMAPINFO structure used 
by these functions and for bitmap initialization is illustrated in Figure 5-1. A 
BITMAPINFOHEABER structure is the same as the BITMAPINFO structure 
shown without the color table. Note that the bits are packed left to right in adjacent 
bits of adjacent bytes with the most significant bits of each byte representing the 
leftmost pels and the data starting with the bottom row of pels and working 
upward. Each row is padded to the nearest 4 byte boundary. The memory require¬ 
ment for a single scanline can therefore be determined by: 

((bitcount * bitmapwidth + 31)/32) * planes * 4 bytes 

As well being stored in DLL resource files and, in the case of bitmaps, application 
exe files, bitmaps, icons, and pointers may also be stored in their own bmp, ico, 
and ptr files. Such files are typically created using the iconedit utility. The file 
begins with one or, for color icons and pointers, two BITMAPFILEHEADER or 
BITMAPARRAYFILEHEADER structures (defined in PMBITMAP.H) identifying 


SAMPLE 5x3 BITMAP 

Pel s 

top row: red green blue red green 

blue red green blue red 

green blue red green blue 


BYTE BitmapData[12] = { 0xA9, OxCA, 
, 0x9C, 0xA9, 
, OxCA, 0x9C, 
} ; 

BYTE Bitmaplnfo = { OxOC, 0x00, 
, 0x05, 0x00 
, 0x03, 0x00 
, 0x01, 0x00 
, 0x04, 0x00 
, 0x00, 0x00, 
, 0x80, 0x00, 
, 0x00, 0x80, 
, 0x80, 0x80, 
, 0x00, 0x00, 
, 0x80, 0x00, 
, 0x00, 0x80, 
, 0x80, 0x80, 
, 0x20, 0x20, 
, OxFF, 0x00, 
, 0x00, OxFF, 
, OxFF, OxFF, 
, 0x00, 0x00, 
, OxFF, 0x00, 
, 0x00, OxFF, 
, OxFF, OxFF, 
} ; 


0x90, 

0x00 

/' 

*■ bottom 1 i ne 

*/ 

OxCO, 

0x00 

/• 

k middle line 

*/ 

OxAO, 

0x00 

/■ 

* top 1ine 

*/ 

0x00, 

0x00 

/* 

cb fixed portion 

*/ 



/* 

width cx = 5 

*/ 



/* 

height cy = 3 

*/ 



/* 

cplanes = 1 

*/ 



/* 

cBitCount = 4 

*/ 

0x00 


/* 

(0) black 

*/ 

0x00 


/* 

(1) dark blue 

*/ 

0x00 


/* 

(2) dark green 

*/ 

0x00 


/* 

(3) dark cyan 

*/ 

0x80 


/* 

(4) dark red 

*/ 

0x80 


/* 

(5) dark pink 

*/ 

0x80 


/* 

(6) brown 

*/ 

0x80 


/* 

(7) pale gray 

*/ 

0x20 


/* 

(8) dark gray 

*/ 

0x00 


/* 

(9) blue 

*/ 

0x00 


/* 

(A) green 

*/ 

0x00 


/* 

(B) cyan 

*/ 

OxFF 


/* 

(C) red 

*/ 

OxFF 


/* 

(D) pink 

*/ 

OxFF 


/* 

(E) yel1ow 

*/ 

OxFF 


/* 

(F) white 

*/ 


Figure 5.1 Bitmap Data Format Example. 
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the type of image (as a bitmap, icon, pointer, color icon, or color pointer), the 
hotspot position for icons and pointers, and an offset to the bitmap data in the 
format described above. Icons and pointers both have the same format and, for 
monochrome icons and pointers, the file contains a double height bitmap providing 
XOR and AND masks. The AND mask determines whether the screen or 
icop/pointer is displayed in each pel position (0 specifies display icon/pointer, 1 
display screen) and the XOR mask determines whether or not each bit of the 
resulting image must be inverted (i.e., black/white or screep/inverse screen). For 
colored icons and pointers, a second bitmap defining the color content is provided. 
In this case, a one bit in the XOR mask will invert the screen but leave the 
icon/pointer color unchanged. The bitmap file format is described in the IBM OS/2 
Programming Reference. 

Icons and pointers may be created (using the iconedit utility) in device indepen¬ 
dent format, in which case the file will contain an array of different versions of the 
icon or pointer to match each of the different device resolutions. 

In order to print an icon or pointer, it can be loaded using WinLoadPointer, and 
WinQueryPointerlnfo can then be used to obtain a POINTERINFO structure. This 
contains handles for the two (double height XOR/AND and color) component 
bitmaps. The double height bitmap must then be separated into its two parts and 
the appropriate BitBlt Rop mix values applied. Because of inversion inconsisten¬ 
cies in handling monochrome bitmaps some older print drivers may require 
slightly different Rop mix values. 


BITMAP DIMENSION FUNCTIONS 

Two rather uninteresting functions exist for storing and retrieving a width and 
height to and from a bitmap. These are: 

GpiSetBitmapDimension; and 

GpiQueryBitmapDimension. 

These functions were included for reasons of compatibility with earlier products. 
They exist for application convenience only and the data set by 
GpiSetBitmapDimension does not in any way affect the bitmap. It is stored with 
the bitmap solely to enable it to be subsequently retrieved. These functions could, 
in fact, be used to store any user data with the bitmap. 


BITMAP AND BITBLT EXAMPLES 

Bitmap and BitBlt operations are illustrated in the following examples. 

The function CreateBitmap in Figure 5—2 illustrates bitmap creation using 
GpiCreateBitmap and initialization of the bitmap by making it the target of 
normal Gpi drawing operations. The DC handle parameter specifies the device for 
which the bitmap is to be created and may be specified as NULL for a display 
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device. It is interesting to note that, for a display at least, when a monochrome 
bitmap is erased its bits are set to all ones and drawing causes the bits to be set to 
zero. Note also that when drawing to a bitmap using page units other than 
PU_PELS for a device (e.g., a printer) that supports a number of different 
resolutions, the dimensions of the image may be incorrect unless the default 
resolution for the device is used. This is because devices are currently unable to 
determine the correct resolution to use for an OD_MEMORY DC (see Appendix 1). 

The function BitBlt in Figure 5-3 illustrates the use of GpiBitBlt, including 
creation of the required PS and OD_MEMORY DC, and bitmap selection using 
GpiSetBitmap. Note that this entire function could be replaced by a single 
GpiWCBitBlt call assuming the source bitmap was initially owned by correct 
target device. 

The function WCBltToPrinter in Figure 5-4 illustrates the transfer of bitmap 
ownership from the display to a printer (say), and the use of GpiWCBitBlt to 
perform a BitBlt operation to the printer. Here a PS and OD_MEMORY DC are 
created, and bitmap selection is performed using GpiSetBitmap, solely for the 
purpose of transferring bitmap ownership. The bitmap is then deselected from the 
PS/DC before issuing GpiWCBitBlt. Note that, assuming the page units are 
PU_PELS and all transforms are set to identity, the GpiWCBitBlt source rectangle 
dimensions must be one larger than the corresponding target rectangle dimen¬ 
sions in order for the true source and target rectangles to be identical. This is 
because the source rectangle is specified in device coordinates that are exclusive 
at two boundaries whereas the target rectangle is specified in world coordinates 
that are inclusive at all four boundaries. 

The function WCBltLoadedBitmap in Figure 5-5 illustrates the use of 
GpiLoadBitmap to load and create a bitmap followed by GpiWCBitBlt to perform 
a BitBlt operation. 

Finally, the function RealizeColorImage in Figure 5-6 illustrates the use of a 
realizable color table for displaying a colored bitmap image. A bitmap is first 
created and selected into a PS associated with an OD_MEMORY DC and a 
realizable color table containing the bitmap color information is created for the PS, 
but not realized. This must occur before initializing the bitmap contents with the 
image data. The same realizable color table is then both created and realized for 
the display PS before GpiBitBlt is issued to display the image. Note that if the 
bitmap is held in a bmp file, it is necessary to open the bitmap file and access the 
bitmap color information in order to use the realize functions. 
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/* crbitmap.c */ 


HBITMAP CreateBitmapCHAB hab, HDC hdc) 

{ 

/* Create a bitmap for the specified device and draw to it. Return the bitmap */ 
/* handle or GPI_ERR0R. */ 

/* */ 

/* inputs: hab anchor block handle */ 

/* hdc DC handle identifying the device for which the bitmap is */ 

/* to be created (can be NULL for the display) */ 

/* */ 

/* returns: HBITMAP bitmap handle or GPI_ERR0R on error */ 

/* */ 


//define BMAPWIDTH 
//define BMAPHEIGHT 
//define BMAPPLANES 
//define BMAPBITCOUNT 
//define BMAPCHARS 
//define NBMAPCHARS 


200 

100 

1 

1 

“This is a Bitmap” 

(LONG)(sizeof(BMAPCHARS)-!) 


BITMAPINFOHEADER 

bmpInfoHdr 

/* bitmap info header 

*/ 

SIZEL 

sizlPS 

/* PS page size 

*/ 

P0INTL 

ptlPosn 

/* coordinate point 

*/ 

HDC 

hdcMem 

/* 0D_MEM0RY DC handle 

*/ 

HBITMAP 

hbm = GPI ERROR 

/* bitmap handle 

*/ 

HPS 

hps = GPI ERROR 

/* PS handle 

*/ 

HBITMAP 

hbmr = HBM ERROR 

/* GpiSetBitmap return code 

*/ 

BOOL 

fRet = FALSE 

/* BOOL return code 

*/ 

bmpInfoHdr.cbFix = sizeof(BITMAPINFOHEADER); 

bmpInfoHdr.cx = BMAPWIDTH ; 

bmpInfoHdr.cy = BMAPHEIGHT ; 

bmpInfoHdr.cPlanes = BMAPPLANES 

bmpInfoHdr.cBitCount = BMAPBITCOUNT ; 



hdcMem = DevOpenDC( hab /* create 0D_MEM0RY DC for display */ 

, 0D_MEM0RY /* -DC type */ 

, /* -token */ 

, 0L /* -DEVOPENDATA count =0 */ 

, NULL /* -DEVOPENDATA (not required) */ 

, hdc /* -device DC handle */ 

); 

sizlPS.cx=0; /* set PS dimensions = zero (default) */ 

sizlPS.cy=0; 

if (hdcMem!=DEV_ERR0R) /* create PS and associate */ 

hps = GpiCreatePS( hab /* -anchor block handle */ 

, hdcMem /* -hdc */ 

, &sizlPS /* -size */ 

, PU_PELS /* -options */ 

GPIF_DEFAULT 
GPIT_MICR0 
GPIA_ASS0C 

); 


Figure 5.2 CreateBitmap Function. 
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if (hps!=GPI_ERR0R) 



/* 

create bitmap 

*/ 

hbm = GpiCreateBitmap( hps 


/* 

-PS handle 

*/ 


, &bmp!nfoHdr 

/* 

-bitmap info header 

*/ 


. OL 


/* 

-options (do not initialize) 

*/ 


. NULL 


/* 

-no initialization data 

*/ 


, NULL 
); 


/* 

-no initialization info table 

*/ 

if (hbm!=GPI_ERROR) 



/* 

select bitmap into PS/DC 

*/ 

hbmr = GpiSetBitmap( 

hps 


/* 

-PS handle 

*/ 

); 

hbm 


/* 

-bitmap handle 

*/ 

if (hbmr!=HBM_ERROR) 



/* 

erase the Bitmap 

*/ 

fRet = GpiErase(hps ); 



/* 

-PS handle 

*/ 

ptlPosn.x = 20L; 
ptlPosn.y = 20L; 
if (fRet) 



/* 

draw to bitmap 

*/ 

fRet = (BOOUGpi CharStri ngAt ( 

hps 





, 

&ptlPosn 





NBMAPCHARS 



) 

BMAPCHARS 


if (hbmr!=HBM_ERROR) 



/* 

deselect bitmap from PS 

*/ 

fRet = GpiSetBitmap( 

hps 


/* 

-PS handle 

*/ 

, 

NULL 


/* 

-bitmap handle (NULL) 

*/ 

) 

!= HBM_ 

ERROR 

&& fRet; 


if (hps!=GPI_ERR0R) 



/* 

destroy PS 

*/ 

fRet = GpiDestroyPS(hps) && 

fRet; 

/* 

-PS handle 

*/ 

if (hdcMem!=DEV_ERROR) 



/* 

close the DC 

*/ 

fRet = DevCloseDCC hdcMem 


/* 

-DC handle 

*/ 

) ! 

= DEV_ERR0R && 

fRet; 


/* if any error occurred attempt to delete bitmap and set return code to 

*/ 

/* GPI_ERR0R. 





*/ 


If (!fRet) 

{ 

if (hbm!=GPI_ERROR) 

Gpi DeleteBitmap(hbm); 
hbm = GPI_E RROR; 

} 


return(hbm); 

} 


Figure 5.2 (continued) 
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/* 

BOOL BitBltC 


HAB hab 

HPS hps 

HBITMAP hbm 

LONG ICount 

PPOINTL aptlPoints 

LONG 1Rop 

ULONG flOptions 


bitblt.c */ 


/* Perform a GpiBitBlt operation using the specified bitmap and parameters, 
/* creating and destroying the necessary PS and 0D_MEM0RY DC. It is assumed 
/* that the bitmap is not initially selected into an 0D_MEM0RY DC. An error 
/* is returned if the specified hps is not associated with a DC. 

/* 


/* inputs: 

hab 

anchor block handle 



/* 

hps 

PS handle 



/* 

hbm 

bitmap handle 



/* 

1 Count 

count of target/source 

coordinate 

points 

/* 

aptlPoints 

array of target/source 

coordinate 

points 

/* 

1 Rop 

rop mix code 


/* 

f1Options 

options 




/* 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


HDC hdc 


/* 

DC handle 

*/ 

HDC hdcMem = DEV ERROR 


/* 

0D_MEM0RY DC handle 

*/ 

HPS hpsMem = GPI ERROR 


/* 

PS handle for 0D_MEM0RY DC 

*/ 

HBITMAP hbmr = HBM ERROR 


/* 

GpiSetBitmap return code 

*/ 

BOOL fRet = FALSE 


/* 

BOOL return code 

*/ 

SIZEL sizlPS 


/* 

PS page size 

*/ 



/* 

query device DC handle 

*/ 

hdc = GpiQueryDevice(hps); 


/* 

-PS handle 

*/ 

if ((hdc!=NULL) && (hdc!=HDC_ERROR)) 

/* 

create 0D_MEM0RY DC for device 

*/ 

hdcMem = DevOpenDC ( hab 


/* 

-anchor block handle 

*/ 

, 0D_MEM0RY 

/* 

-DC type 

*/ 

“* ” 


/* 

-token 

*/ 

; ol 


/* 

-count of DEVOPENSTRUC items 

*/ 

, NULL 


/* 

-DEVOPENSTRUC data 

*/ 

, hdc 
); 


/* 

-DC handle identifying device 

*/ 

siz1 PS.cx=0; 


/* 

set PS dimensions = zero (default) 

*/ 

sizlPS.cy=0; 





if (hdcMem!=DEV_ERR0R) 


/* 

create PS and associate 

*/ 

hpsMem = GpiCreatePS( hab 


/* 

-anchor block handle 

*/ 

, hdcMem 

/* 

-DC handle for association 

*/ 

, &siz1 PS 

/* 

-PS size 

*/ 

, PU PELS 

/* 

-options 

*/ 

GPIF DEFAULT 




| GPIT_MICRO 




GPIA ASSOC 

) ; 




if (hpsMem!=GPI_ERROR) 


/* 

select bitmap into PS/DC 

*/ 

hbmr = GpiSetBitmap( hpsMem 


/* 

-PS handle 

*/ 

, hbm 


/* 

-bitmap handle 

*/ 


); 


Figure 5.3 BitBlt Function. 
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if (hbmr!=HBM ERROR) 

/* 

perform the GpiBitBlt 

operation 

*/ 

fRet = (BOOL)GpiBitBlt( hps 

/* 

-target PS handle 


*/ 

, hpsMem 

/* 

-source PS handle 


*/ 

, ICount 

/* 

-count of points 


*/ 

, aptlPoints 

/* 

-array of source and 

target points 

*/ 

, 1 Rop 

/* 

-Rop mix value 


*/ 

, flOptions 
); 

/* 

-options 


*/ 

if (hbmr!=HBM_ERR0R) 

/* 

deselect bitmap 


*/ 

fRet = GpiSetBitmap( hpsMem 

/* 

-PS handle 


*/ 

, NULL 

) != HBM_ERR0R 

/* 
&& ■ 

-bitmap handle (NULL) 
fRet; 


*/ 

if (hpsMem!=GPI_ERR0R) 

/* 

destroy PS 


*/ 

fRet = GpiDestroyPS(hpsMem) && fRet; /' 

* -PS handle 


★ 

if (hdcMem!=DEV_ERR0R) 

/* 

destroy DC 


*/ 

fRet = DevCloseDC( hdcMem 

/* 

-DC handle 


*/ 


) != DEV_ERROR && fRet; 


return(fRet); 

} 


Figure 5.3 (continued) 


/* wcbltprt.c */ 

BOOL WCB1tToPrinter(HAB hab, HPS hps, HBITMAP hbm) 

{ 

/* Using a bitmap owned by the display, BitBlt to a different device such as */ 
/* a printer (identified by the DC associated with hps) using GpiWCBitBlt */ 
/* Note that a PS and 0D_MEM0RY DC are required for the bitmap in order to */ 
/* transfer ownership to the new device, even though these are not actually */ 

/* required by GpiWCBitBlt. It is assumed that the bitmap is not initially */ 

/* selected into any PS/DC and that any ’start doc’ and ’end doc’ escapes */ 

/* that are required by the printer are issued before and after this */ 

/* function by the caller. */ 

/* */ 

/* Note that if the page units are PU_PELS, the source and target rectangles */ 
/* will be identical and no stretching or compression will occur. As the */ 

/* source rectangle is in device coordinates (which are inclusive-exclusive) */ 
/* then (for GpiWCBitBlt) its dimensions must be one larger than those */ 

/* of the correspond!'ng target rectangle (which is in world coordinates). */ 
/* */ 

/* */ 

/* inputs: hab anchor block handle */ 

/* hps PS handle */ 

/* hbm bitmap handle */ 

/* */ 


//define XTARGORG 50L 
//define YTARGORG 50L 


HDC hdc ; /* 
HDC hdcMem = DEV_ERR0R ; /* 
HPS hpsMem = GPI_ERR0R ; /* 
HBITMAP hbmr = HBM_ERR0R ; /* 
BOOL fRet = FALSE ; /* 
BITMAPINFOHEADER bmplnfo ; /* 
SIZEL siz1 PS ; /* 
POINTL aptlPoints[4] ; /* 


device DC handle */ 
0D_MEM0RY DC handle */ 
PS handle */ 
GpiSetBitmap return code */ 
BOOL return code */ 
bitmap info header */ 
PS page size */ 
target/source coordinate array */ 


Figure 5.4 WCBltToPrinter Function. 
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hdc = GpiQueryDevice(hps); /* query device DC handle */ 

if ((hdc!=NULL) && (hdc!=HDC_ERROR)) /* create OD_MEMORY DC for device */ 

hdcMem = DevOpenDCC hab /* -anchor block handle */ 

, 0D_MEMORY /* -DC type */ 

, /* -token */ 

, OL /* -DEVOPENDATA count =0 */ 

, NULL /* -DEVOPENDATA (not required) */ 

, hdc /* -DC handle identifying device */ 

); 

sizlPS.cx=0; /* set PS dimensions = zero (default) */ 

sizlPS.cy=0; 

if (hdcMem!=DEV_ERR0R) /* create PS and associate */ 

hpsMem = GpiCreatePS( hab /* -anchor block handle */ 

, hdcMem /* -DC handle for association */ 

, &sizlPS /* -PS size */ 

, PU_PELS /* -options */ 

GPIF_DEFAULT 
GPIT_MICRO 
GPIA_ASS0C 

); 

/* select bitmap into this PS/DC to */ 
if (hpsMem!=GPI_ERROR) /* transfer ownership to new device */ 

hbmr = GpiSetBitmap( hpsMem /* -PS handle */ 

, hbm /* -bitmap handle */ 

); 

if (hbmr!=HBM_ERR0R) /* deselect bitmap */ 

hbmr = GpiSetBitmap( hpsMem /* -PS handle */ 

, NULL /* -bitmap handle (NULL) */ 

); 

bmplnfo.cbFix = sizeof(BITMAP INFOHEADER); 

if (hbmr!=HBM_ERR0R) /* query bitmap parameters */ 

fRet = GpiQueryBitmapParameters( hbm /* bitmap handle */ 

, &bmpInfo /* BITMAPINFOHEADER structure */ 
); 

aptlPoints[0].x = XTARGORG ; /* target rectangle left */ 

aptlPoints[0].y = YTARGORG ; /* target rectangle bottom */ 

aptlPoints[l].x = XTARGORG+bmpInfo.cx-1 ; /* target rectangle right */ 

aptlPoints[1] .y = YTARGORG+bmpInfo.cy-1 ; /* target rectangle top */ 

aptlPoints[2].x = OL ; /* source rectangle left */ 

aptlPoints[2].y = OL ; /* source rectangle bottom */ 

aptlPoints[3].x = bmplnfo.cx ; /* source rectangle left */ 

aptlPoints[3].y = bmplnfo.cy ; /* source rectangle right */ 

if (fRet) /* perform the BitBlt operation */ 

fRet = (BOOL)GpiWCBitBlt( hps /* -target PS handle */ 

, hbm /* -source bitmap handle */ 

, 4L /* -count of points */ 

, aptlPoints /* -array of source & target points */ 

, R0P_SRCC0PY /* -Rop mix value */ 

, BB0_0R /* -options */ 

); 


Figure 5.4 (continued) 
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if (hpsMem!=GPI_ERROR) 

fRet = GpiDestroyPSChpsMem) && fRet; /* destroy the PS */ 

if (hdcMem!=DEV_ERROR) 

fRet = DevCloseDC(hdcMem)!=DEV_ERR0R && fRet; /* close the DC */ 

return (fRet); 

} 

Figure 5.4 (continued) 


/* wbltload . c */ 


BOOL WCB1tLoadedBitmap(HPS hps, USHORT usResourceld) 

{ 

/* Load a bitmap from the application EXE file using GpiLoadBitmap and BitBit */ 
/* it to the PS using GpiWCBitBlt. */ 

/* */ 

/* Note that if the page units are PU_PELS, the source and target rectangles */ 
/* will be identical and no stretching or compression will occur. As the */ 

/* source rectangle is in device coordinates (which are inclusive-exclusive) */ 
/* then (for GpiWCBitBlt) its dimensions must be one larger than those */ 

/* of the correspond!' ng target rectangle (which is in world coordinates). */ 
/* */ 

/* inputs: hps PS handle */ 

/* usResourceld Bitmap resource Id */ 

/* */ 

//define XWTARGORG 50L 
//define YWTARGORG 50L 

HBITMAP hbm ; /* bitmap handle */ 

BOOL fRet = FALSE ; /* BOOL return code */ 

POINTL aptlPoints[4] ; /* target/source coordinate point array */ 

BITMAPINFOHEADER bmplnfo ; /* bitmap info header */ 

/* load bitmap from application exe file */ 
hbm = GpiLoadBitmap( hps /* -PS handle identifying device */ 

, (HMODULE)NULL /* -Resource ID NULL i.e. appl. EXE file */ 

, usResourceld /* -ID in resource file */ 

, OL /* -bitmap width 0 - use original value */ 

, OL /* -bitmap height 0 - use original value */ 

); 

bmplnfo.cbFix = sizeof(BITMAPINFOHEADER); 

if (hbm!=GPI_ERR0R) /* query bitmap parameters */ 

fRet = GpiQueryBitmapParameters( hbm /* bitmap handle */ 

, &bmpInfo /* BITMAPINFOHEADER structure */ 

); 


Figure 5.5 WCBltLoadedBitmap Function. 
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aptlPoints[0].x = XWTARGORG ; /* target rectangle left */ 

aptlPoints[0].y = YWTARGORG ; /* target rectangle bottom */ 

aptlPoints[1].x = XWTARGORG+bmpInfo.cx-1 ; /* target rectangle right */ 

aptlPoints[i].y = YWTARGORG+bmpInfo.cy-1 ; /* target rectangle top */ 

aptlPoints[2].x = 0L ; /* source rectangle left */ 

aptlPoints[2].y = 0L ; /* source rectangle bottom */ 

aptlPoints[3].x = bmplnfo.cx ; /* source rectangle left */ 

aptlPoints[3].y = bmplnfo.cy ; /* source rectangle right */ 

if (fRet) /* perform the BitBlt operation */ 

fRet = GpiWCBitBltC hps /* -target PS handle */ 

, hbm /* -source bitmap handle */ 

, 4L /* -count of points */ 

, aptlPoints /* -array of source and target points */ 

, R0P_SRCC0PY /* -Rop mix value */ 

, BB0_0R /* -options */ 

) != GPI_ERR0R; 

if (hbm!=GPI_ERR0R) /* delete bitmap */ 

fRet = GpiDel eteBitmap(hbm) && fRet; /* -bitmap handle */ 


return (fRet); 

} 

Figure 5.5 (continued) 


/* realize.c */ 

BOOL RealizeColorImage( HAB hab 
, HPS hps 

, PBYTE pblnitData 
, PBITMAPINFO pbmiInfoTable 
) 


/* Display an 8 bit per pel scanned image using the color realize functions */ 
/* if supported. Note that GpiUnrealizeColorTabl e must be issued subsequently */ 
/* to unrealize the color table. */ 
/* */ 
/* inputs: hab anchor block handle */ 
/* hps PS handle */ 
/* pblnitData Bitmap image data */ 
/* pbmiInfoTable Bitmap BITMAPINFO table */ 
/* */ 
/* If the input data is provided by a .bmp bitmap resource file, the input */ 
/* parameters can be established from the data as shown below. */ 
/* */ 
/* PBYTE pbBitmapFi1eData ; pointer to start of .bmp file data */ 
/* PBITMAPFILEHEADER pbmfh ; pointer to BITMAPFILEHEADER */ 
/* */ 
/* if (((PBITMAPARRAYFILEHEADER)pbBitmapFi1eData)->usType == BFT_BITMAPARRAY) */ 
/* pbmfh = (PBITMAPFILEHEADER)((PBYTE)pbBitmapFi1eData */ 
/* + sizeof(BITMAPARRAYFILEHEADER) - sizeof(BITMAPFILEHEADER)); */ 
/* else */ 
/* pbmfh = (PBITMAPFILEHEADER)pbBitmapFi1eData; */ 
/* if (pbmfh->usType!=BFT_BMAP) */ 
/* return(FALSE); */ 
/* pbmiInfoTable = (PBITMAPINFO)((PBYTE)pbmfh+sizeof(BITMAPFILEHEADER) */ 
/* _ - sizeof(BITMAPINFOHEADER)); */ 
/* pblnitData = (PBYTE)pbBitmapFi1eData+pbmfh->offBits; */ 
/* */ 


Figure 5.6 RealizeColorlmage Function. 
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HBITMAP 

hbm = GPI_ERR0R 


/* 

bitmap handle 

*/ 

HBITMAP 

hbmr = HBM ERROR 


/* 

HBITMAP return code 

*/ 

BOOL 

fRet = FALSE 


/* 

BOOL return code 

*/ 

HPS 

hpsMem = GPI ERROR 


/* 

PS handle 

*/ 

HDC 

hdcMem = DEV_ERR0R 


/* 

DC handle 

*/ 

POINTL 

aptlPoints[3] 


/* 

target/source coordinate point array 

*/ 

LONG 

1NumColors 


/* 

number of bitmap color table colors 

*/ 

PBYTE 

pbColorTable = NULL 


/* 

color table pointer 

*/ 

PBYTE 

pbColors 


/* 

color table pointer 

*/ 

PBYTE 

pbColorlnfo 


/* 

color info 

*/ 

SIZEL 

si zlPS 


/* 

PS page size 

*/ 

HDC 

hdc = HDC_ERR0R 


/* 

DC handle 

*/ 

INT 

i 


/* 

array index 

*/ 

ULONG 

ul Realize 


/* 

realize option 

*/ 

LONG 

1DevColorSupport 


/* 

color table support device cap 

*/ 

LONG 

1NumDeviceColors 


/* 

number of colors device cap 

*/ 





/* allocate color table memory 

*/ 

INumColors = (L0NG)pow(2.0, (double)pbmiInfoTable->cBitCount) ; 


pbColors 

= pbColorTable = mal1oc((SHORT)lNumColors*sizeof(LONG)); 


if (pbColorTable!=NULL) 



/* query DC handle for target device 

*/ 

hdc = 

GpiQueryDevice(hps); 



/* -PS handle 

*/ 

if( hdc! 

=HDC_ERR0R) 



/* open 0D_MEM0RY DC 

*/ 

hdcMem 

= DevOpenDCC hab 



/* -anchor block handle 

*/ 


, 0D_MEM0RY 


/* -DC type 

*/ 


a ^ >> 



/* -token 

*/ 


! 0L 



/* -DEVOPENSTRUC count (0) 

*/ 


, NULL 



/* -DEVOPENSTRUC (n/a) 

*/ 


, hdc 
); 



/* -compatible hdc 

*/ 

si zl PS . cx = 0 ; 





si zl PS . cy = 0 ; 





if (hdcMem != DEV ERROR) 



/* create PS and associate 

*/ 

hpsMem 

= GpiCreatePSC hab 



/* -anchor block handle 

*/ 


, hdcMem 


/* -DC handle for associate 

*/ 


, &siz1 PS 


/* -page size 

*/ 


, PU PELS 


/* -options 

*/ 


| GPIT MICRO 





1 GPIA ASSOC 





); 

/* construct the color table for GpiCreateLogColorTable from the BITMAPINFO */ 
/* rgb color array */ 

if(hpsMem!=GPI_ERROR) 

{ 

pbColorlnfo = (PBYTE)pbmiInfoTable + pbmiInfoTable->cbFix; 

for (i=0; i<(I NT)1NumColors; i++ ) 

{ 

*pbColors = *pbColorlnfo; 

*(pbColors+1) = *(pbColorlnfo+l); 

*(pbColors+2) = *(pbColorInfo+2); 

*(pbColors+3) = 0; 
pbColors += 4; 
pbColorlnfo += 3; 

} 


Figure 5.6 (continued) 
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/* query number of colors supported */ 


fRet = DevQueryCaps( hdc /* -DC handle */ 

, CAPS_C0L0RS /* -start */ 

, 1L /* -count */ 

, &1NumDeviceColors /* -returned number of colors */ 

); 

} 

if (fRet) /* query realize support */ 

fRet = DevQueryCaps( hdc /* -DC handle */ 

, CAPS_COLOR_TABLE_SUPPORT /* -start */ 

, 1L /* -count */ 

, &1DevColorSupport /* -returned flags */ 

); 

if (1DevColorSupport & CAPS_COLTABL_REALIZE) 
ulRealize = LCOL_REALIZABLE; 

el se 

ulRealize = OL; 


/* create logical color table for */ 
/* bitmap PS (must be realizable 

if (fRet) /* but need not be realized) */ 

fRet = GpiCreateLogColorTable( hpsMem /* -PS handle */ 

, LCOL_RESET /* -valid options */ 

| ulRealize 

, LCOLF_CONSECRGB /* -format */ 

, OL /* -start index */ 

, min( INumColors /* -number of colors */ 

, 1NumDeviceColors) 

, (PLONG)pbColorTable /* -RGB table data */ 
); 

if(fRet) /* create and initialize bitmap */ 

hbm = GpiCreateBitmap( hpsMem /* -PS handle */ 

, (PBITMAPINFOHEADER)pbmiInfoTable /* -info header */ 

, CBM_INIT /* -options */ 

, pblnitData /* -initialization info table */ 

, pbmiInfoTable /* -initialization data */ 

); 

if (hbm!=GPI_ERROR) /* select bitmap into PS/DC */ 

hbmr = GpiSetBitmap( hpsMem /* -PS handle */ 

, hbm /* -bitmap handle */ 

); 

/* create realizable color table for */ 
if (hbmr!=HBM_ERR0R) /* target PS */ 

fRet = GpiCreateLogColorTable( hps /* -PS handle */ 

, LCOL_RESET /* -options */ 

| ulRealize 

, LCOLF_CONSECRGB /* -format */ 

, OL /* start index */ 

, min( INumColors /* number of colors */ 

, 1NumDeviceColors) 

, (PLONG)pbColorTable/* RGB color table data*/ 

) && fRet; 

if (fRet && (1DevColorSupport & CAPS_COLTABL_REALIZE)) /* realize color */ 

/* table if realize supported */ 

fRet = GpiRealizeColorTable(hps); /* -PS handle */ 


Figure 5,6 (continued) 
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aptlPoints[0].x = 0L; /* target rectangle left */ 

aptlPoints[0] .y = 0L; /* target rectangle bottom */ 

aptlPointsCl].x = pbmiInfoTable->cx; /* target rectangle right */ 

aptlPoints[1].y = pbmiInfoTable->cy; /* target rectangle top */ 

aptlPoints[2].x = 0L; /* source rectangle left */ 

aptlPoints[2].y = 0L; /* source rectangle bottom */ 

if (fRet) /* perform the BitBlt operation */ 

fRet = (BOOUGpi Bi t B11 ( hps /* -target PS handle */ 

, hpsMem /* -source bitmap handle */ 

, 3L /* -count of points */ 

, aptlPoints /* -array of source and target points */ 

, R0P_SRCC0PY /* -Rop mix value */ 

, BB0_0R /* -options */ 

); 

if (hbmr!=HBM_ERR0R) /* deselect the bitmap */ 

fRet = GpiSetBitmap( hpsMem /* -PS handle */ 

, NULL /* -bitmap handle (NULL) */ 

) != HBM_ERR0R && fRet; 

if (hbm!=HBM_ERR0R) /* delete bitmap */ 

fRet = GpiDeleteBitmap(hbm) && fRet; /* -bitmap handle */ 

if (hpsMem!=GPI_ERR0R) /* destroy the PS */ 

fRet = GpiDestroyPS(hpsMem) && fRet; /* -PS handle */ 

if (hdcMem!=DEV_ERR0R) /* destroy the DC */ 

fRet = DevCloseDCC hdcMem /* -DC handle */ 

) != DEV_ERR0R && fRet; 

free(pbColorTable); /* free memory */ 


return(fRet); 

} 


Figure 5.6 (continued) 
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Color Tables 


An application may specify a color attribute for drawing (e.g., using 
GpiSetColor) as either an RGB or index value, according to the color table mode 
(index or RGB). A logical color table in index mode is a map of color index to 
RGB value. In RGB mode, RGB values are specified directly without any 
mapping. 

An RGB color value is either a three or four byte integer containing eight bit red 
(R), green (G), and blue (B) intensity values (i.e., R*65536+G*256+B). Note that 
in memory, the order of the bytes is reversed and they will appear as BGR values. 
The presentation drivers provide psychometric rather than linear RGB support. 
This means that increased RGB value gives a visually linear increase in intensity 
rather one based on photon intensity. 

An example of the index mode color table model is illustrated in Figure 6-1. Note 
that there is a further mapping between the logical color table RGB values and 
those in the physical device palette to obtain the device RGB color that most closely 
matches the required color. If the same color needs to be reused (i.e., set) a number 
of times then index mode offers a clear performance advantage over RGB mode. 
In RGB mode the RGB to nearest physical color mapping is repeated each time the 
color is set whereas in index mode it is performed only once. 


THE STANDARD DOLOR TABLE 

The default (or reset) color table mode is index mode and the system provides a 
default color table of 16 entries with symbolic constants defined for each, plus 
certain other predefined non-index values as illustrated below. 
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PS LOGICAL 
COLOR TABLE 
(INDEX MODE) 


GlpiS®tColor(hps, 6L)- 


13 

14 

15 


INDEX 

RGB 

VALUE 

PHYSICAL 

INDEX 


PHYSICAL 

DEVICE 

PALETTE 

0 

RGB-0 

5 


1 

RGB-1 

10 


INDEX 

2 

RGB-2 

4 


VALUE 

3 

RGB-3 

15 

0 

RGB-4a 

4 

RGB-4 

0 

1 

RGB-8a 

5 

RGB-5 

3 

2 

RGB-12a 


RGB-6 

9 


3 

RGB-5a 



7 

RGB-7 

8 


4 

RGB-2a 

8 

RGB-8 

1 


5 

RGB-0a 

9 

RGB-9 

13 


6 

RGB-lOa 

10 

RGB-10 

6 


7 

RGB-I4a 

11 

RGB-11 

14 


8 

RGB-7a 

12 

RGB-12 

2 



RGB-6a 


13 

RGB-13 

12 

10 

RGB-la 

14 

RGB-14 

7 

11 

RGB-15a 

15 

RGB-15 

11 

12 

RGB-13a 


RGB-9a 


RGB-1la 


RGB-3a 


Note: RGB-6a, for example, is the device RGB color that most closely 
matches RGB-6, the requested RGB color. 

Figure 6.1 Logical and Physical Color Table Model. 


Predefined non- 

•index values: 


Value -5 

CLR_FALSE 

All color planes 0 

-4 

CLR_TRUE 

All color planes 1 

-3 

CLR_DEFAULT 

Default Color 

-2 

CLR_WHITE 

White 

-1 

CLR BLACK 

Black 


Predefined (standard) color table index values: 
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Index 0 CLR_BACKGROUND Device background 




color 

(SYSCLR_WINDOW 

for display) 

1 

CLR_BLUE 

Blue 

2 

CLR_RED 

Red 

3 

CLR_PINK 

Pink 

4 

CLR_GREEN 

Green 

5 

CLR_CYAN 

Cyan 

6 

CLRYELLOW 

Yellow 

7 

CLR_NEUTRAL 

Device foreground color 
(SYSCLRJWINDOW- 
TEXT for display) 

8 

CLR_DARKGRAY 

Dark Gray 

9 

CLR_DARKBLUE 

Dark Blue 

10 

CLRJDARKRED 

Dark Red 

11 

CLR_DARKPINK 

Dark Pink 

12 

CLRJDARKGREEN 

Dark Green 

13 

CLR_DARKCYAN 

Dark Cyan 

14 

CLR_BROWN 

Brown 

15 

CLR_PALEGRAY 

Pale Gray 


RGB values in both index and RGB mode are mapped to the nearest available color 
in the predefined device palette. A device may provide additional colors for use in 
area fill by dithering, which is a process whereby unavailable colors are simulated 
by using different colors for alternate pels. 

Clearly, for devices that support fewer than 16 colors, it is possible for more than 
one index in the standard color table color to map to the same actual RGB device 
color. 


LOGICAL COLOR TABLE CREATION 

Using GpiCreateLogColorTable, an application can provide its own set of indexed 
RGB mappings to define its own logical color table. This is illustrated by the 
function CreateLogicalColorTable in Figure 6—2. The maximum index value sup¬ 
ported for a particular device can be determined using DevQueryCaps 
(CAPS_COLOR_INDEX) and should normally be at least 63, even for a mono¬ 
chrome device. 



148 


OS/2 PRESENTATION MANAGER GPl 


\ 


GpiCreateLogColorTable includes both a format and an options parameter. The 
format parameter specifies one of the following: 


LCOLF_RGB 

This sets the color table to RGB mode. 


LCOLFJNDRGB 

This loads the supplied color data, which consists of an array of index-RGB pairs. 
Depending on its index value, each new pair of index-RGB values will either 
replace an existing entry or extend the table. If the color table was previously in 
RGB mode, it is switched to index mode and reset to the default color table before 
the new data is loaded. 


LC0LF_C0N8ECRGB 

This loads the supplied color data, which consists of an array of RGB values with 
consecutive indices starting from a specified index. Depending on its index value, 
each new RGB value will either replace an existing entry or extend the table. If 
the color table was previously in RGB mode, it is switched to index mode and reset 
to the default color table before the new data is loaded. 

The options parameter allows any combination of the following options to be 
specified: 


LCOLJRESET 

This resets the color table to the default color table before loading the new data. 
This reset is implicit whenever the format parameter specifies a switch from RGB 
to index mode. 


LCOLF_REALSZABlE 

If supported by the presentation driver, this creates a realizable color table (see 
below). This option is valid only for index mode (i.e., LCOLFJNDRGB or 
LCOLF_CONSEGRGB) and will force the LCOL_PURECOLOR option for any 
drivers that support realizable color tables. 
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LCOLF_PURECOLOR 

This indicates that only pure colors Eire required. Dithering may not be used to 
simulate unavailable colors. 


REALIZABLE COLOR TABLES 

For non-realizable color tables in either index or RGB mode, each RGB value is 
mapped to the nearest available RGB value in the fixed physical color palette of 
the device. Realizable color table support enables an application to create its own 
realizable color table and then realize it (i.e., reload the device color palette with 
application specified RGB values). This enables high quality scanned images to be 
displayed using bitmaps. 

The actual colors obtained when a realizable color table is realized depend, of 
course, on the color resolution of the particular device. The RGB values are 
assumed to be psychometric and are corrected accordingly by the driver before 
they are loaded into the physical device palette. It is not possible to load the device 
palette with unmodified RGB values from an application. 

For a bitmap, no remapping of bitmap content data occurs when the correspond¬ 
ing PS color table (i.e., the color table of the PS associated with the OD_MEMORY 
DC into which the bitmap is selected) is realized. For performance reasons, the 
color mapping for a bitmap occurs when its contents are initialized. A suitable 
realizable color table must therefore be created (but not realized) before the 
bitmap data is initialized. 

Realizable color tables are supported only in index mode. To be realized, a color 
table must first be created with the LCOLF_REALIZABLE Option. A realizable 
color table can then be realized and unrealized using: 

GpiRealizeColorTable; and 

GpiUnrealizeColorTable. 

A complete screen repaint is essential after each of these operations in order to 
obtain the correct display screen appearance. 

Clearly, reloading the device color palette will affect the appearance of all 
windows on the display screen. To avoid interfering with other applications visible 
on the display screen, GpiRealizeColorTable should only be issued when the 
relevant window is maximized and has the input focus. GpiUnRealizeColorTable 
should be issued as soon as the window is unmaximized or loses the input focus. 

For hard copy devices such as printers, realize is not applicable. These do not 
have the problem of displaying the output from different applications simulta¬ 
neously and should therefore always provide the best color match possible for the 
requested colors. 

While a realizable color table is unrealized, its colors will be displayed from the 
physical device palette exactly as if it were realized, and are therefore unlikely to 
appear correct. 

On early levels of IBM OS/2 Version 1.2, GpiRealizeColorTable was not sup- 
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ported by any driver. Support was added, together with gray scale palette im¬ 
provements for image support, on a 1.2 Corrective Service Diskette and also on 
Version 1.3. Support is for the 8514/A display driver only and it is not currently 
supported by any other driver. 

Realizable color tables should not be dissociated from their DC or the 
LCOLF_REALIZABLE (and LCOLF_PURECOLOR) option will be lost. See chap¬ 
ter 5 for a description of how bitmaps are used with realizable color tables. 


COLOR QUERIES 

A number of color query functions exist as follows: 


GpiQuerylogColorlable 

For Index Mode, this returns the contents of the logical color table. 

For RGB Mode, it provides a return value indicating that the table is in RGB mode. 

GpSQueryCoIorData 

This returns the format (default, Index Mode, RGB Mode) and largest index 
currently loaded for the logical color table. 

GpiQueryReaSColors 

This returns the RGB values of the actual colors available on the associated output 
device. If applicable, it can be used to obtain the values that would apply when a 
realizable color table is realized. 

GpiQueryNearestColor 

This returns the actual RGB color of the associated device that is closest to a 
specified RGB value. 

GpiQueryColorlndex 

This returns the logical color index for the associated device color that is closest to 
a specified RGB value. 

GpiQueryRGBGolor 

This returns the actual RGB value that will be provided by the associated device 
for a specified logical color index. If applicable, it can be used to obtain the value 
that would apply when a realizable color table is realized. 
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/* createlo.c */ 


BOOL CreateLogical ColorTable( HPS hps ) 

{ 

/* Reset the logical color table and load it in index mode with indexed-RGB */ 
/* values. */ 

/* */ 

/* inputs: hps PS handle */ 

/* */ 

#define NALTABLEI 32L 

BOOL fRet ; /* BOOL return code */ 

static LONG alTable[NALTABLEI] = 

{ OL, OxOOOOOOOOL /* (0) black (RGB_BLACK) */ 

, 1L, 0x00000080L /* (1) dark blue */ 

, 2L, 0x00008000L /* (2) dark green */ 

, 3L, 0x00008080L /* (3) dark cyan */ 

, 4L, 0x00800000L /* (4) dark red */ 

, 5L, 0x00800080L /* (5) dark pink */ 

, 6L, 0x00808000L /* (6) brown */ 

, 7L, 0x00808080L /* (7) pale gray */ 

, 8L, 0x00202020L /* (8) dark gray */ 

, 9L, OxOOOOOOFFL /* (9) blue (RGB_BLUE) */ 


, 10L, OxOOOOFFOOL /* (A) green (RGB_GREEN) */ 

, 11L, OxOOOOFFFFL /* (B) cyan (RGB_CYAN) */ 

, 12L, OxOOFFOOOOL /* (C) red (RGB_RED) */ 

, 13L, OxOOFFOOFFL /* (D) pink (RGB_PINK) */ 

, 14L, OxOOFFFFOOL /* (E) yellow (RGBJi'ELLOW) */ 

, 15L, OxOOFFFFFFL /* (F) white (RGB_WHITE) */ 

}; 

fRet = GpiCreateLogColorTable( hps 

, LCOL_RESET 
, LCOLF_INDRGB 
, OL 

, NALTABLEI 
, alTable 
); 

return(fRet); 

} 


Figure 6.2 CreateLogicalColorTable Function. 


/* PS handle */ 
/* option */ 
/* format */ 
/* start index */ 
/* number of alTable elements*/ 
/* RGB color table array */ 






Coordinate Spaces and Transformation 


The Gpi transform functions provide a mechanism for two dimensional scaling, 
translation, rotation, and shear in graphics pictures (and text). Device indepen¬ 
dence is provided by allowing an application to define its picture in device 
independent page units. 

Chapter 1 illustrated how to perform simple rotation, scaling, and shear using 
the transformation ‘helper’functions: GpiRotate, GpiScale, and GpiTranslate, and 
also pointed out that such operations could also be accomplished by specifying the 
required matrices directly without using the ‘helper’ functions. This is illustrated 
in the examples below (see Appendix 3 for a brief introduction to coordinate 
transformations and matrices). 

For rotation, the following two sequences are exactly equivalent, performing a 
30-degree counterclockwise rotation about the point (100,150). 


{ 

/* rotate by 30 degrees counterclockwise about the point (100,150) */ 

ptlPosn.x = 100L; /* x center of rotation */ 

ptlPosn.y = 150L; /* y center of rotation */ 

GpiRotate( hps, &matlfModel, TRANSF0RM_REPLACE, MAKEFIXED(30,0) , &ptlPosn ); 
GpiSetModelTransformMatrix( hps, 9L, &matlfModel, TRANSF0RM_ADD); 

} 

and 

{ 

static MATRIXLF matlfModel = { 0x10000, 0L, 0L, 0L, 0x10000, 0L, 0L, 0L, 1L }; 

/* translate the point (100,150) to the origin */ 

matlfModel.1M31 = -100L; /* x translation (-100) */ 

matlfModel.1M32 = -150L; /* y translation (-150) */ 

GpiSetModelTransformMatrix( hps, 9L, &matlfModel, TRANSF0RM_ADD); 
matlfModel.1M31 = matlfModel.1M32 = 0L; 
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/* rotate by 30 

degrees counterclockwise 


*/ 

matlfModel.fxMll 

= 0x0000DD63; 

/* 

Cos(30)*0xl0000 rotation 

*/ 

matlfModel.fxM12 

= 0x00008000 L; 

/* 

Sin(30)*0xl0000 rotation 

*/ 

matlfModel.fxM21 

= 0xFFFF8000; 

/* 

-Sin(30)*0xl0000 rotation 

*/ 

matlfModel.fxM22 

= 0x0000DD63; 

/* 

Cos(30)^0x10000 rotation 

*/ 

GpiSetModelTransformMatrix( hps, 9L, 

&matl fModel, TRANSF0RM_ADD); 


matlfModel.fxMll 

= matlfModel.fxM22 = 

0x10000; 



matlfModel.fxM12 

= matl fModel.fxM21 = 

0L; 



/* translate by 

(100,150) back to the 

original 

position 

*/ 

matlfModel.1M31 

= +100L; 

/* 

x translation (+100) 

*/ 

matlfModel.1M32 

= +150L; 

/* 

y translation (+150) 

*/ 


GpiSetModelTransformMatrix( hps, 9L, &matlfModel, TRANSFORM_ADD); 
matlfModel.1M31 = matlfModel.1M32 = OL; 


For scaling, the following two sequences are exactly equivalent, performing scal¬ 
ing by a factor of 2.0 in both the x and y direction about the point (100,150). 


{ 

/* scale by 2.0 in both x and y direction about the point (100,150) */ 

afxScale[0] = MAKEFIXED(2,0); /* x scaling = 2.0 */ 

afxScale[1] = MAKEFIXED(2,0); /* y scaling = 2.0 */ 

ptlPosn.x : = 100L; /* x center of scaling */ 

ptlPosn.y == 150L; /* y center of scaling */ 

GpiSeale( hps, &matlfModel, TRANSF0RM_REP LACE, afxScale, &pt1P o s n ) ; 

GpiSetModelTransformMatrix( hps, 9L, &matlfModel, TRANSF0RM_ADD); 

} 

and 


static MATRIXLF matlfModel = { 0x10000, 0L, 0L, 0L, 0x10000, 0L, 0L, 0L, 1L }; 


/* translate the point (100,150) to the origin */ 

matlfModel.1M31 = -100L; /* x translation (-100) */ 

matlfModel.1M32 = -150L; /* y translation (-150) */ 

GpiSetModelTransformMatrix( hps, 9L, &matlfModel, TRANSF0RM_ADD); 
matlfModel.1M31 = matlfModel.1M32 = 0L; 

/* scale both x and y by a factor of 2.0 */ 

matlfModel.fxMll = 0x00020000; /* x scaling (times 2.0) */ 

matlfModel.fxM22 = 0x00020000; /* y scaling (times 2.0) */ 

GpiSetModelTransformMatrix( hps, 9L, &matlfModel, TRANSF0RM_ADD); 
matlfModel.fxMll = matlfModel.fxM22 = 0x10000; 

/* translate by (100,150) back to the original position */ 

matlfModel.1M31 = +100L; /* x translation (+100) */ 

mat 1fModel.1M32 = +150L; /* y translation (+150) */ 

GpiSetModelT ransf ormMatrix( hps, 9L, &matlfModel, TRANSF0RM_ADD); 
matlfModel.1M31 = matlfModel.1M32 = 0L; 

} 


For translation, the following two sequences are exactly equivalent, performing 
translations of +50 and +100 in the x and y directions respectively. 
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{ 


/* translate by +50 and +100 in the x and 

y directions respectively 

*/ 

ptlPosn.x = 50L; 



ptlPosn.y = 100L; 



GpiTranslate( hps 

/* -PS handle 

*/ 

, &matlfModel 

/* -transform matrix 

*/ 

, TRANSF0RM_REPLACE 

/* -options 

*/ 

, &ptlPosn 

) . 

/* -translation coordinates 

*/ 

GpiSetModelTransformMatrix( hps 

/* -PS handle 

*/ 

, 9 L 

/* -number of matrix elements 

*/ 

, &matlfModel 

/* -transform matrix 

*/ 

, TRANSF0RM_ADD 

/* -options 

*/ 


} 

and 


static MATRIXLF matlfModel = { 0x10000, 0L, 0L, 0L, 0x10000, 0L, 0L, 0L, 1L }; 


/* translate by +50 and +100 in the x and y 
matlfModel.1M31 = +50L; 

matlfModel.1M32 = +100L; 

GpiSetModelTransformMatrix( hps 

, 9 L 

, &matlfModel 
, TRANSFORM_ADD 
) ; 

matlfModel.1M31 = mat 1fModel.1M32 = 0L; 

} 


directions respectively 
/* x translation (+50) 

/* y translation (+100) 

/* -PS handle 

/* -number of matrix elements 
/* -transform matrix 
/* -options 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


Note from the above examples that (when transforming a figure about a given 
point) for operations other than translation, the figure origin must first be trans¬ 
lated to (0,0) before the required (rotate, scale, shear, etc.) matrix operation is 
performed, and translated back to its required position afterward. This is import¬ 
ant to avoid undesirable translations (which occur when the translation offset is 
scaled or rotated together with the figure). This translation is explicit when using 
the 'set transform’ functions directly, whereas with the 'helper functions’ GpiRot- 
ate and GpiScale it is implicit. Note also that the TRANSFORM_ADD option 
allows the transform to be incrementally accumulated in steps, rather than being 
overwritten each time. 

The above examples illustrate use of the model transform matrix, which is 
intended for transforming individual elements and figures within the picture 
during drawing. Chapter 1 also mentioned the default view matrix that is provided 
for scaling and scrolling the whole picture. The GPI, in fact, provides a hierarchy 
of coordinate spaces and transforms each with its own distinct purpose. 

Application specified coordinates are called world coordinates. These are trans¬ 
formed by the various presentation space transforms, to provide the device inde¬ 
pendent version of the picture in the PS page from where it is rendered to the 
device. The units of the PS page together with the device resolution determine the 
device transform required to ensure that an inch (say) in the PS page appears as 
an inch on the device. These conversions from world to presentation page to device 
coordinates via the presentation space and device transforms are illustrated in 
Figure 7-1. 
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Figure 7.1 Presentation Space and Device Transforms. 

PAGE UNITS 

As mentioned above, the page units together with the device resolution determine 
the device transform. Page units are typically fractions of an inch or meter, but 
can also be specified as device coordinates (i.e., PU_PELS) if required. The page 
units (of the PS page) are specified as parameters to GpiCreatePS and GpiSetPS 
(see chapter 2). For a cached PS, the page units default to PU_PELS. 

The system provides the following choice of page units: 

PU__ARBITRARY page units cause the picture to be displayed as 
large as possible in the available device output area while preserv¬ 
ing its aspect ratio (such that a circle remains a circle). For a display 
window, the available device output area is assumed to be the maxi¬ 
mized window or screen size. 

PU_PELS page units are device units. These are pels for a raster 
device and for a plotter are equal to the minimum line increment. 

PU_LOMETRIC page units are 0.1 mm. 

PU_HIMETRIC page units are 0.01 mm. 

PU_LOENGLISH page units are 0.01 inches. 

PU_HIENGLISH page units are 0.001 inches. 

PU_TWIP8 page units are 1/1440 inches (i.e., 1/20 of a printers 
point). 

Although not recommended, an application can modify the device transform using 
GpiSetPageViewport to define its own page units (see below). 

In addition to specifying the page units, an application must specify the page 
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dimensions. For PU_ARBITRARY page units, page dimensions are important in 
determining the drawing limits and the aspect ratio of the visible picture on the 
device. The application may specify any convenient values up to OxQTFFFFFF 
(134217727) but very small values should be avoided. 

For page units other than PU_ARBITRARY, the precise page dimensions are, 
with certain exceptions, fairly unimportant. If the PS is to be used for printing, 
then it is good practice to match the page dimensions to the size of the output form 
where this is possible, otherwise they can be defaulted, or set to some sensible 
values that minimize the risk of internal overflow. Apart from with PU_ARBI- 
TRARY page units, the page dimensions are important under the following 
conditions: 


• If GpiSetPageViewport is being issued by an application to define its 
own page units, then the page dimensions are important in that, 
together with the page viewport, they define the new device trans¬ 
form and page units (see below). 

• When printing via the spooler, if queue processor options other then 
“XFM=0” (which is not the default) are specified then the page 
dimensions should accurately reflect the size of the output form. This 
will ensure that the ‘FIT=’ and ‘ARE- (scale to fit, etc.) parameters 
provide the correct results. 

• If the PS is used for recording a MetaFile, the page dimensions will 
be recorded in the MetaFile as the picture dimensions and may be 
used when the MetaFile is subsequently displayed. 


PRESENTATION SPACE TRANSFORMS 

Apart from device transform, three presentation space transforms are visible to 
an application. These are: 

• Model Transform (including segment and instance transform). 

• Viewing Transform. 

• Default Viewing Transform. 

Other system transforms, such as the translation associated with the position of 
the window on the display screen, do exist, but these are transparent to an 
application. 

Model transform, viewing transform and default viewing transform are all 
presentation space transforms affecting the appearance of the device independent 
picture in the PS page, whereas device transform renders the PS page contents to 
the device. The transformation 'pipeline' showing the order in which these trans¬ 
forms are applied is illustrated in Figure 7—2 and can be represented mathemati¬ 
cally as: 

[Xd Yd 1] = [Xw Yw 1].[M].[V].[DVT].[D] 
where: 
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Xd Yd = device coordinates; 

Xw Yw = world coordinates; 

M = model transform matrix; 

V = viewing transform matrix; 

DVT = default viewing transform matrix; and 
D = device transform matrix. 

In practice, world coordinates are not actually converted to each intermediate 
coordinate space. The transforms are combined internally allowing coordinates to 
be transformed directly from world to device coordinates by the system in a single 
operation. Nevertheless, the illustration in Figure 7-2 provides an accurate and 
useful model for understanding the operation and purpose of the individual 
matrices. 


World 

Coordinate 

Space 



V v 


Model 

Space 


JL 

M 


Viewing Transform 


Default 

Pag® 

Coordinate 

Space 



Page 

Coordinate 

Space 


Device 

Coordinate 

Space 



Figure 7.2 Gpi Transformation Pipeline. 
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The model and viewing transforms are picture attributes that can be varied 
during drawing for the purpose of picture construction, whereas the default 
viewing (and device) transform are environment attributes that should be estab¬ 
lished before the picture is drawn. 

Many applications need not be concerned with, or use, all of the available 
transforms. As stated above, the basic model transform should be used for 
transforming individual elements within a picture and the default viewing 
transform for scrolling and scaling (i.e., pan and zoom) the entire picture. In 
addition to the GpiSetModelTransformMatrix function, the instance and segment 
transforms provide two additional ways of controlling the model transform 
drawing attribute. Instance transform is a model transform specified with 
GpiCallSegmentMatrix, for use with called retained segments, and segment 
transform is a model transform used exclusively at the start of retained segments. 
Viewing transform is provided to enable the contents of an entire graphics 
segment to be transformed without interference from (model) transform opera¬ 
tions inside the segment. 

The GpiSetModelTransformMatrix and GpiSetDefaultViewMatrix functions 
both have an options parameter controlling the way in which the new and existing 
matrix values are combined. This may specify one of the following: 

TRANSFORM_REPlACE 

The new transform matrix elements provided with the call are used to replace the 
existing values. 

TRANSFORM_ADD 

The new and existing transform matrix elements are combined by concatenating 
the new matrix after the existing matrix. This can be represented mathematically 
by: 

[matrix] = [existing matrix]. [new matrix] 

or : [Xout Yout 1] = [Xin Yin 1].[existing matrix].[new matrix] 

In a pipeline model (such as that used in Figure 7-2), the output of the original 
matrix is effectively transformed further by the new matrix (which is below it). 
This option is more commonly used than TRANSFORM_PREEMPT. 

TRANSFORM_PREEMPT 

The new and existing transform matrix elements are combined by concatenating 
the new matrix before the existing matrix. This can be represented mathemati¬ 
cally by: 

[matrix] = [new matrix].[existing matrix] 

or: [Xout Yout 1] = [Xin Yin l].[new matrix].[existing matrix] 
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In a pipeline model (such as that illustrated in Figure 7-2), the new matrix is 
placed before the original, and the output of the new matrix is effectively trans¬ 
formed further by the original matrix (which is below it). 


MATRIX PARAMETER FORMATS 

As explained in Appendix 3, any two dimensional transform operation can be 
represented by the general equations: 

Xout = Xin.Mll + Yin.M21 + M31 

Yout = Xin.M12 4- Yin.M22 + M32 

which are be represented in matrix form as: 

“ M11M12 0 ~ 

M21 M22 0 
_ M31 M32 1 _ 

These matrix elements are passed as a parameter to any of the ‘set transform 
matrix’ functions in a MATRIXLF structure in the order: 

[ Mil M12 0 M21 M22 0 M31 M32 1 ] 

The corresponding fields of the MATRIXLF structure are: 

[fxMll fxM12 1M13 fxM21 fxM22 1M23 1M31 1M32 1M33 ] 

The elements fxMll, fxM12, fxM21, and fxM22 are of type FIXED while the 
remainder are of type LONG. FIXED numbers are four-byte values with a notional 
binary point between bytes 3 and 4. (See chapter 1 for a description of FIXED 
numbers.) 


COORDINATE LIMITS 

As explained in chapter 1, in order to avoid coordinate overflow, device coordinates 
must not exceed the (16 bit) range 0xFFFF8000-Ox0Q007FFF (-32768 to 32767) 
and world, and all other, coordinates must not exceed the (28 bit) range 
OxF8000000—0x07FFFFFF (-134217728 to 134217727) and must also conform to 
the 16 bit device coordinate range when transformed to device coordinates. 

Note also the further restriction that world coordinates must be in the (16 bit) 
range 0xFFFF8000-0x00007FFF (-32768 to 32767) if the PS was created with the 
GPIF_SHORT format option and that it is an application responsibility to ensure 
this. It will not be policed. This restriction applies to coordinates stored in retained 
segments and MetaFiles. The coordinates will be truncated to 16 bits if the 
GPIF_SHORT format option is used. 
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Where only rectangular transformations are used, the 16 bit device coordinate 
limits (-32768, -32768) and (32767, 32767) can be back transformed (using 
GpiConvert) to world coordinate space to obtain the world coordinate limits that 
will avoid device coordinate overflow In the more complex case, when rotation and 
shear are used, the device coordinate limits must be back transformed, using 
GpiConvert, to model space and compared against the boundary data of the picture 
(see chapter 10). Even this relies on the viewing and the default viewing trans¬ 
forms providing only rectangular transformations. 


GPICONVERT 


GpiConvert is an extremely useful transform function that enables an application 
to transform coordinates from any specified coordinate space to any other. This is 
used, for example, by the function DisplayTextBuffer in chapter 1 to convert the 
window rectangle from device to world coordinates. 


A DETAILED DESCRIPTION OF THE TRANSFORMS 

The remainder of this chapter provides a detailed description of the different 
transform types. 

Model Transform 

Model transform is a picture drawing attribute that can be varied during drawing 
for the purpose of picture construction. This is is the work-horse' transform that 
should be used for all picture modeling and construction purposes. 

Using the TRANSFORMJffiPU4CE, TRANSFORM_ADD, and TRANS- 
FORM_PREEMPT options, an application can, if required, construct its own model 
transform pipeline of any complexity similar to that in Figure 7-2 but consisting 
only of model transform matrices. The concatenation of all the matrices in such an 
application model transform pipeline provides the value of the model transform 
drawing attribute represented by the single model transform in Figure 7-2. 

Note that whenever model transform is changed, this is equivalent to beginning 
a new sub-picture in a new world coordinate space (see Figure 7-2). 

There are three forms of model transform, all of which contribute to the model 
transform drawing attribute. These are: 

1. Model Transform itself. 

This is set and queried using: 

GpiSetModelTransformMatrix; and 

GpiQueryModelTransformMatrix. 

GpiSetModelTransformMatrix will set (or push and set) the current 
value of model transform drawing attribute, store a set (or push and 
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set) model transform element in the currently open retained segment, 
or both, depending on drawing mode. If attribute mode is AM_PRE- 
SERVE (see chapter 3), the push and set rather than the set versions 
of the above apply. The actual orders stored in a retained segment by 
this function are illustrated in Figure 7-3. As explained above the 
TRANSFORM_REPLACE, TRANSFORM_ABD, and TRANS- 
FORM_PREEMPT options control the way in which the new matrix is 
combined with the existing model transform drawing attribute. Where 
an element (i.e., OCODE_GSTM/OCODE_GPSTM) is being stored in 
a retained segment or MetaFile, they control the flags (overwrite, 
concatenate after or concatenate before) stored in the order. These 
flags are applied when the segment is subsequently drawn. 


GpiOpenSegment ()-— 

(Non-Identity PS Matrix) 

GpiSet/QuerySegment( )—— 
TransformMatrix(..segid..) 


FIRST ELEMENT- 


GpiSetModelTransfors 

Matrix()——-- 

(AM_N0PRESERVE) 


GpiS etModeIT ransform 

Matrix( )■--—- 

(AM JPRESERVE) 


Call 

Segment 

Element 


^Segment Viewing Transform: is created on GpiOpenSegment 

cannot be queried 

Figure 7.3 Retained Segment Transform Orders. 
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■> Set Viewing .Transform 
Order (GSTVf 
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■> Push & ■ Segment is not directly 

Set Model Transform Prolog visible to an 

Order (GSTM) application 

— -——-———— — unless recorded 

End Prolog (GEPROL) in a MetaFile 


Set Model Transform 
•> Matrix Order (GSTM) 


Push and Set Model 
■> Transform Matrix 
Order (GPSTM) 
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2. Instance Transform. 

This is set using: 

GpiC all S e gmentMatr ix 

Instance transform is the name used for the model transform matrix 
specified as a parameter to GpiCallSegmentMatrix. When the same 
object (e.g., a wheel) is to be drawn more than once with different 
positions and sizes, it can be stored once in a retained segment and 
displayed by calling this segment multiple times. The instance trans¬ 
form enables the position and size of each instance of the object to be 
controlled by the matrix parameter on the individual calls. 

GpiCallSegmentMatrix will either push and set’the current value of 
the model transform drawing attribute and then call the segment and 
pop the old value, store a sequence of orders in the currently open 
retained segment, or both, depending on drawing mode. In the re¬ 
tained case, the orders stored are as illustrated in Figure 7-3. and 
include push and set model transform (GPSTM), call segment 
(GCALLS), and pop (GPOP). The begin and end element orders serve 
only to bracket together the group of orders identifying them as a 
single element. 

Note that regardless of attribute mode, in both non-retained and 
retained cases the ‘push and set’ version of set model transform is 
always generated by GpiCallSegmentMatrix, and the call is always 
followed by a pop function that ensures that the original value of model 
transform attribute is preserved across the call. 

Operation of the TRANSFORMJREPLACE, TRANSFORM_ADD, 
and TRANSFORM_PREEMPT options with GpiCallSegmentMatrix 
is identical to that for GpiSetModelTransformMatrix. 

3. Segment Transform. 

This is set and queried using: 

GpiSetSegmentTransformMatrix; and 

GpiQuerySegmentTransformMatrix. 

GpiSetSegmentTransformMatrix applies only to retained segments 
and does not modify the model transform drawing attribute until the 
segment concerned is subsequently drawn. It creates and stores a 
push and set model transform’ order (GPSTM) in an internal prolog 
at the start of an existing retained segment (see Figure 7-3). If a 
segment has no internal prolog, GpiSetSegmentTransformMatrix will 
create one and insert it at the start of the segment. 

If TRANSFORM_REPLACE is specified with GpiSetSegment 
TransformMatrix, the existing value in the retained segment (if any) 
is replaced. If TRANSFORM_ADD or TRANSFORM_PREEMPT are 
specified, the new value is concatenated with the existing value in the 
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retained segment (or with an identity matrix if the segment currently 
has no segment matrix). When the segment is drawn, the model 
transform drawing attribute is always modified by the segment trans¬ 
form in an additive manner (i.e., the segment model transform matrix 
is concatenated after the current model transform matrix drawing 
attribute). 


Wiemrlog Transform 

Although it does satisfy certain specific requirements such as sub-picturing, the 
viewing transform is the least useful of the available transforms and for the maj ority 
of applications it can be ignored. Viewing transform is set and queried using: 

GpiSetViewingTransformMatrix; and 

GpiQueryViewingTransformMatrix. 

Like model transform, viewing transform is also a picture drawing attribute that 
can be varied during drawing for the purpose of picture construction. Unlike model 
transform, however, viewing transform cannot be used with non-retained drawing 
primitives outside segments; it affects only drawing primitives or elements that 
occur inside retained or non-retained segments (i.e., between GpiOpenSegment 
and GpiCloseSegment). Its purpose is to provide an additional transform capable 
of transforming the entire (model space) output of a segment without being 
overridden by model transforms within the segment. 

An example of viewing transform use would be for importing a sub-picture into 
an existing picture where the sub-picture may have different page units from the 
target. The size and position of the target rectangle can be used together with the 
sub-picture boundary data to determine the viewing transform required to provide 
the correct transformation. This is illustrated by the function SubpictureMetaFile 
in chapter 11. In this example, as in most normal uses, viewing transform provides 
only rectangular transformation but it is also capable of more general transform 
operations (e.g., rotation) if required. This does, however, introduce complications 
into certain operations such as that of converting the boundary rectangle from 
model to page coordinate space. 

Note that whenever viewing transform is changed for a new segment or group 
of segments, this is equivalent to beginning a new sub-picture in a new model 
space (see Figure 7-2). 

Like segment transform, viewing transform in a retained segment is stored in 
an internal prolog at the segment start (as a set viewing transform order in this 
case). However, whereas the segment transform is just a normal model transform 
that can be replaced or pre-empted by subsequent model transform orders in the 
segment, viewing transform is immune from any such interference from the 
segment contents. 

GpiSetViewingTransform does not update the viewing transform drawing attri¬ 
butes of retained segments directly, but merely updates a matrix stored in the PS 
(see chapter 3). The TRANSFORMJREPLACE, TRANSFORM_ADD, or TRANS- 
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FORM_PREEMPT options control the way in which the new matrix is combined 
with the existing PS matrix. The viewing transform drawing attribute is always 
updated (from the segment prolog matrix) by a replace operation when the 
segment is drawn. 

When GpiOpenSegment is issued, the PS matrix is used to update the viewing 
transform drawing attribute or to construct a set viewing transform' order (GSTV) 
in an internal prolog at the start of a new retained segment, or both, depending on 
drawing mode (see Figure 7-3). If the PS matrix value is identity, no internal 
prolog is created when a segment is created. The segment, if chained, behaves as 
if it contains an implicit 'set viewing transform' order with an identity matrix (i.e., 
when the segment is drawn, the viewing transform drawing attribute is reset to 
identity at the start of the segment). The viewing transform drawing attribute is 
always reset to identity at the end of any drawn root segment and by GpiCloseSeg- 
ment when drawing mode is DMJDRAW or DMJDRAWANDRETAIN (see Figure 
3-1). 

When creating a segment for use as a called segment, the PS viewing transform 
matrix should first be reset to identity (using GpiSetViewingTransformMatrix) 
before issuing GpiOpenSegment to ensure that no set viewing transform order is 
stored in the segment. Such an order in a called segment would destroy the 
transform pipeline model illustrated in Figure 7—2 and for this reason is ignored. 
If present, it could result in an invalid interchange file when used to create a 
MetaFile. 

Note that for IBM OS/2 Version 1.3 at least, neither the viewing transform 
drawing attribute nor the retained segment viewing transform matrix value can 
be queried. Also, the retained segment viewing transform matrix value cannot be 
modified. This is something of a disadvantage that affects the usefulness of this 
particular transform function. 


Default Viewing Transform 

Default viewing transform is set and queried using: 

GpiSetDefaultViewMatrix; and 
GpiQueryDefaultViewMatrix. 

Default viewing transform is a PS environment attribute rather than a drawing 
attribute and should not, therefore, be varied during drawing. Like the other 
transforms, its default value is identity. It purpose is to enable the application to 
scroll and scale the entire picture in the PS page. For this reason, although capable 
of operations such as shear and rotation, it is not really intended for these (with 
the exception, perhaps, of 90-degree rotation). 

GpiSetDefaultViewMatrix always updates the default viewing transform (envi¬ 
ronment) drawing attribute directly. The TRANSFORM JXEPLACE, TRANS- 
FORM_ADD, or TRANSFORM_PREEMPT options control the way the new ma¬ 
trix is combined with the existing matrix as described above. 
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Qewio© Transform 

It is the device transform that provides the requested page units for a particular 
device. For page units of PUPELS, its value is identity. For other page units, it is 
the transform from the page to the device that yields the required page units for 
the particular device resolution. For any of the standard page units, its value is 
established with the page units by: 

GpiCreatePS; 

GpiSetPS (without PS_NORESET option); 

GpiPlayMetaFile (with RES_RESET option); and 

Cached PS allocation (page units PU_PELS, device transform 
Identity). 

Where its requirements are fully satisfied by the standard page units, an applica¬ 
tion need not concern itself with device transform. If essential, however, it can 
modify the device transform to define its own page units. This is accomplished 
using GpiSetPageViewport. 

Unlike other transforms, device transform is defined by two rectangles, those of 
the page and the page viewport, with the actual matrix element values determined 
as follows: 


Mil = (X2 - XI)/W 
M12 = 0 
M21 = 0 

M22 = (Y2 - Yl)/H 
M31 = XI + 1/2*(Mil - 1) 

M32 = Y1 + 1/2*(M22 - 1) 

(XI, Yl) and (X2,Y2) are the bottom left and top right coordinates of the page 
viewport, with the top right coordinate (X2,Y2), exclusive (i.e., outside the rectan¬ 
gle) because these are in device coordinates. W and H are the width and height of 
the PS page where the page coordinates are (0,0) and (W-1,H-1). These points are 
both inclusive (i.e., inside the rectangle). 

This definition of device transform is illustrated in Figure 7-4. Like the page 
viewport, which consists of a rectangular array of device pixels, the PS page is 
viewed as a rectangular array of cells. One might assume that the center bottom 
left cell (0,0) would transform to the center bottom left pel (XI,Yl) but this is 
not the case. In the GPI model, the bottom left corner of the bottom left cell 
(-1/2,-1/2) transforms to the bottom left corner of the bottom left pel (X1-1/2,Y1- 
1/2). Similarly, the top right corner of the top right cell (W-l/2, H-l/2) transforms 
to the top right corner of the top right pel (X2-l/2,Y2-l/2). This model gives 
greater accuracy when (say) the number of cells is small compared to the 
number of pels. 
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(W-l/2,H-l/2) 



Figure 7A Device Transform Model. 


As the page coordinates are fixed by the page dimensions on PS creation (or by 
GpiSetPS), page units can only be changed by modifying page viewport coordi¬ 
nates. The page viewport is set and queried using: 

GpiSetPageViewport; and 

GpiQueryPageViewport. 

Note that page viewport is not automatically the same as the rectangle returned 
from WinQueryWindowRect and neither the page nor the page viewport are 
clipping rectangles. These two rectangles merely serve to define the device trans¬ 
form that provides the required page units. 

As mentioned earlier, either or both page dimensions may be defaulted causing 
them to be set to the corresponding default device dimensions or, in the case of a 
display, the display screen size. In the case of PU_ARBITRARY page units, the size 
of one dimension will be constrained, where necessary, to ensure that the picture 
aspect ratio is preserved. 

The system will compute page viewport coordinates for existing page units even 
when GpiSetPageViewport has not been issued. These can then be queried and 
used in the calculation of new page viewport values or used at any time with 
GpiSetPageViewport to restore the page units to their original value. 

It is recommended that, wherever possible, applications should use standard 
page units rather than defining their own. This is because application defined page 
units are not stored in either a MetaFile or an OD_QUEUED (PM_Q_STD) print 
file (see chapters 11 and 12). 




COORDINATE SPACES AND TRANSFORMATION 


165 


With one exception, page viewport (i.e., device transform) should not be used for 
operations such as scaling and scrolling. The exception is for PU_ARBITRARY 
page units where it is required to scale the picture to fit the window as it is sized. 
The function ScaleToFitWindow in Figure 7-5 illustrates how to scale a PU_AR= 
BITRARY presentation space to fit the window (by default it is scaled to the 
display screen size rather than the maximized window size as documented). 

Sewlce Transform Translation iemewa! 

As pointed out above, by default (0,0) in the page will not always transform exactly 
to (0,0) in device coordinates. When the resolution of the device is high compared 
to that of the page, a small positive translation will occur in both x and y directions. 
For example, if there are three pels for each page unit then (0,0) in the page will 
transform to the center of the bottom left 3x3 cell, that is, to point (1,1) on the 
device. This does not normally present a problem unless a device happens to 
require every available pel for some particular operation. For example, with some 
devices this translation can cause the maximum number of characters per row to 
be reduced from 80 to 79. In theory, a similar problem can also exist vertically but 
this is less likely and has never been reported. 

If this does create a problem there is a choice of solutions. 

• Change to higher resolution page units (e.g., from PU_LOENGLISH 
to PU_HIENGLISH) or increase the page dimensions for PU_ARBI- 
TRARY page units. This will increase the resolution of the page 
making it closer to that of the device. 

• Apply a suitable scaling factor using GpiSetDefaultViewMatrix to 
scale the world coordinates down, increasing the resolution of world 
coordinate space. The world coordinates specified for drawing would 
then, of course, need to be increased by the same factor. The exact 
scale factor used is not critical but should be sufficient to make the 
resolution of world coordinates the same as, or greater than, that of 
the device coordinates. 

• Apply a correction to the device transform to remove the unwanted 
translation as illustrated by the function RemoveTranslation in Fig¬ 
ure 7—6. This should also work successfully when printing via the 
spooler using data type PM_Q_RAW. If the data type is PM_Q_STD 
an equivalent correction can be achieved using the XLT= 5 Print 
Queue Processor parameter (see Appendix 2). 
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/ ' scltofit.c */ 

BOOL SealeToFitWindow(HPS hps, HWND hwnd, PRECTL prclPvInit) 


/* Scale a picture in a PS with PILARBITRARY page units to fit the window */ 
/* when it has been sized. */ 

/* */ 

/* inputs: hps PS handle */ 

/* hwnd client window handle */ 

/* prclPvInit a pointer to the initial page viewport (queried before */ 

/* GpiSetPageViewport has been issued) */ 

/* */ 


BOOL 

fRet 


/* 

BOOL return code 

*/ 

SIZEL 

sizlPS 


/* 

PS size 

*/ 

RECTL 

rclWind 


/* 

window rectangle 

*/ 

P0INTL 

ptlTR 


/* 

TR coords of ideal max window 

*/ 

FIXED 

fxScaleFactor 


/* 

scale factor 

*/ 

LONG 

1PvpHeight 


/* 

new page viewport height 

*/ 

LONG 

1PvpWidth 


/* 

new page viewport width 

*/ 

RECTL 

rclPvp 


/* 

new page RECTL values 

*/ 




/* 

query window coordinates 

*/ 

fRet = 

WinQueryWindowRect( hwnd 

/* 

-window handle 

*/ 



, &rclWind 

/* 

-returned coordinates 

*/ 

if (fRet) 

), 

/* 

query PS size 

*/ 

fRet 

= GpiQueryPS( hps 

/* 

-PS handle 

*/ 


, &sizlPS 

/* 

-returned size 

*/ 


) ! = 

GPI_ERR0R; 







/* 

set page viewport to 

*/ 

if (fRet) 


/* 

maximized size 

*/ 

fRet 

= GpiSetPageViewport( hps 

/* 

-PS handle 

*/ 



, prclPvInit 

/* 

-page viewport 

*/ 


); 


ptlTR.x = sizlPS.cx 

-1; 


/* convert PS page dimensions 

*/ 

ptlTR.y = sizlPS.cy 

-1; 


/* to device coordinates to 

*/ 

if (fRet) 



/* give ideal maximized window 

*/ 

fRet = GpiConvert( hps 


/* -PS handle 

*/ 


, CVTC PAGE 


/* -source 

*/ 


, CVTC DEVICE 


/* -target 

*/ 


. 1L 


/* -count of points 

*/ 


, &ptlTR 
) ; 


/* -points 

*/ 

/**********^********^ 

/* 

*************** 

*:******■> 


*r** / 

*/ 

/* If current window 

x/y > ideal window maximized x/y aspect ratio 

*/ 

/* calculate scale 

factor to fill 

window 

vertically 

*/ 

/* else 



*/ 

/* calculate scale 

factor to fi 11 

window 

horizontally 

*/ 

/* 




*/ 


if (((rclWind.xRight*OxlOOOO)/rc!Wind.yTop) > ((ptlTR.x*0xl0000)/ptlTR.y)) 
fxScaleFactor = (rclWind.yTop * 0x10000) / ptlTR.y; 
else 

fxScaleFactor = (rclWind.xRight * 0x10000) / ptlTR.x; 


Figure 7.5 ScaleToFitToWindow Function. 
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/* */ 

/* Use scale factor to calculate new page viewport height and width then */ 

/* calculate new page viewport coordinates. */ 

/* */ 

/★I*****************************************************************************/ 


IPvpWidth = (prclPvlnit->xRight - prcl Pvlni t->xLeft)*fxScal eFactor/OxlOOOO; 

!PvpHeight= (prclPvlnit->yTop - prclPvlnit->yBottom)*fxScaleFactor/OxlOOOO ; 

rclPvp.xLeft = (IPvpWidth / sizlPS.cx - 1) / 2; 

rclPvp.yBottom = (IPvpHeight / sizlPS.cy - 1) / 2; 

rclPvp.xRight = rclPvp.xLeft + IPvpWidth; 

rclPvp.ylop = rclPvp.yBottom + IPvpHeight; 


if (fRet) 

/* 

set the new page viewport 

*/ 

fRet = GpiSetPageViewport( hps 

/* 

-PS handle 

*/ 

, &rclPvp 

/* 

-page viewport 

*/ 


); 

return(fRet); 

} 

Figure 7.5 (continued) 


/* 

removetr 

c */ 

BOOL RemoveTranslation(HPS hps) 

r 



1 

/* Remove the translation component from the 

device transform 

*/ 

/* 


*/ 

/* inputs: hps PS handle 


*/ 

/* 


*/ 

RECTL rclViewport ; 

/* page viewport 

*/ 

BOOL fRet ; 

/* BOOL return code 

*/ 

POINTL ptlCoord ; 

/* coordinate point 

*/ 

ptlCoord.x = OL; 

/* convert (0,0) from page to 

*/ 

ptlCoord.y = OL; 

/* device space 

*/ 

fRet = GpiConvert( hps 

/* -PS handle 

*/ 

, CVTC PAGE 

/* -source 

*/ 

, CVTC DEVICE 

/* -target 

*/ 

, 1L 

/* -count 

*/ 

, &ptlCoord 
) . 

/* -coordinate point 

*/ 

if (fRet) 

/* query page viewport 

*/ 

fRet = GpiQueryPageViewport( hps 

/* -PS handle 

*/ 

, &rclViewport 
); 

/* -page viewport rectangle 

*/ 

rclViewport.xLeft -= ptlCoord.x; 

/* adjust the page viewport 

*/ 

rclViewport.xRight -= ptlCoord.x; 

/* coordinates to remove any 

*./ 

rcl Vi ewport.yBottom -= ptlCoord.y; 

/* translation and set the 

*/ 

rcl Viewport.yTop -= ptlCoord.y; 

/* page viewport 

*/ 

if (fRet) 



fRet = GpiSetPageViewport( hps 

/* -PS handle 

*/ 

, &rclViewport 

/* -page viewport rectangle 

*/ 


); 


return(fRet) ; 

} 


Figure 7.6 RemoveTranslation Function. 
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Clipping And Regions 


APPLICATION CLIPPING FUNCTIONS 

The GPI provides four different application clipping functions providing both 
picture and environment clipping. These provide clipping to a single rectangle, a 
shape defined by a number of rectangles, or an arbitrary shape of almost unlimited 
complexity. By default, each of these functions provides no clipping. 

The four GPI clipping functions are: 

Viewing Limits 

The viewing limits define a single clipping rectangle in model space. This is a 
primitive drawing attribute that can be varied as the picture is drawn. Its purpose 
is to enable part of a picture to be clipped to a single rectangle in model space 
during picture construction. Points on all boundaries of the viewing limits are 
inclusive (i.e., inside the rectangle) and are therefore unclipped. See chapter 3 for 
a description of the viewing limits attribute functions. 


Graphics Field 

The graphics field defines a single clipping rectangle in the PS page. This is an 
environment attribute that should be set initially and not varied as the picture is 
drawn. Its purpose is to enable the entire picture to be clipped to a single rectangle 
in the page. Points on all boundaries of the graphics field are inclusive (i.e., inside 
the rectangle) and are therefore unclipped. The graphics field is set and queried 
using: 


18S 
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GpiSetGraphicsField 
GpiQueryGraphicsF ield 

Note that graphics field does not conform to the MetaFile interchange architecture 
and, although it can be used in MetaFiles for interchange with other OS/2 
workstations, it should not be used when recording MetaFiles for interchange with 
other products (see chapter 11). 

Clip Path 

The clip path defines an arbitrary clipping shape of any complexity (subject to 
internal implementation limits). A clip path is defined initially as a normal path 
in world coordinates using normal GPI drawing primitives. Once output' and 
converted to a clip path, it becomes fixed in device coordinates and is unaffected 
by subsequent transform changes. Clip path is a picture clipping object that can 
be varied as the picture is drawn. Its purpose is to enable part of, or the entire 
picture, to be clipped to any complex shape. Points on all boundaries of the clip 
path are inclusive (i.e., inside the clip path) and are therefore unclipped. See 
chapter 3 for a further description of the clip path. 

Clip Region 

The clip region provides a clip boundary defined by one or more rectangles in 
device space. This is a PS environment attribute that should be set initially and 
not varied as the picture is drawn. Its purpose is to enable the entire picture to be 
clipped to a complex shape defined by a number of rectangles in device space. As 
it is defined in device space, clip region is not subject to rounding errors that may 
occur with other clipping functions. Atypical use is to provide the clipping required 
by the newly exposed area that must be redrawn after (say) a scroll operation is 
performed using GpiBitBlt. 

Note that the clip region does not conform to the MetaFile interchange architec¬ 
ture and although it can be used in MetaFiles for interchange with other OS/2 
workstations, it should not be used when recording MetaFiles for interchange with 
other products (see chapter 11). 

A further description of region and clip region functions is provided below. 

REGIONS AND CLIP REGIONS 

A region is an object defined by one or more rectangles in device coordinates. 
Regions are most commonly used to provide clipping but can also be used for area 
fill. The region functions provide an application with a means of creating and 
modifying regions and clip regions and filling a region using the AREABUNDLE 
attributes. 

All rectangles used with region and clip region functions are specified in device 
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coordinates, are inclusive at the bottom and left coordinate boundaries, and 
exclusive at the top and right coordinate boundaries (i.e., the bottom and left 
boundaries are inside the rectangle and are unclipped; the top and right bound¬ 
aries are outside the rectangles and are clipped). 

A region must be explicitly selected as a clip region to enable it to be used for 
clipping. 

Region Functions 

When a region is initially created, its shape is determined by an array of one or 
more rectangles. Regions are created and destroyed using: 

GpiCreateRegion; and 

GpiDestroyRegion. 

Regions can be combined and modified using: 

GpiCombineRegion; 

GpiOffsetRegion; and 
GpiSetRegion. 

Functions also exist to query whether two regions are identical, to query whether 
a point or rectangle lies inside the region, to return the bounding rectangle of a 
region, and to return an array of rectangles defining the region shape. These are 
performed using: 

GpiEqualRegion; 

GpiPtlnRegion; 

GpiRectlnRegion; 

GpiQueryRegionBox; and 

GpiQueryRegionRects. 

A region can be filled using the AREABUNDLE attributes by: 

GpiPaintRegion 

Clip Region Functions 

A region is converted to a clip region using: 

GpiSetClipRegion 

GpiSetClipRegion returns the handle of the previous clip region (or NULL). While 
a region is selected as the clip region, the normal region functions (above) are 
invalid for that region. 

Clip regions can be modified by excluding or intersecting with a specified 
rectangle using: 
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GpiExcludeClipRectangle; and 
GpilntersectClipRectangle. 

These functions automatically create a clip region if one does not already exist 
(such a region does not need to be destroyed by the application when no longer in 
use). 

Functions also exist to query the bounding rectangle of a region and to query the 
handle of the currently selected clip region. These are: 

GpiQueryClipBox; and 

GpiQueryClipRegion. 

Region Complexity 

A number of the above region and clip region functions return the complexity of 
the region or clip region as one of: 

RGN_NULL The region or clip region is a null rectangle (no clip¬ 
ping). 

RGN_RECT The region or clip region is a simple rectangle. 

RGN_COMPLEX The region or clip region is a complex shape de¬ 
fined by two or more rectangles. 
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Orders, Elements, and Segments 


DRAWING ORDERS 

A drawing order is a sequence of bytes in a graphics segment representing a 
particular primitive or attribute drawing function. Each drawing primitive or 
primitive attribute recorded in a retained graphics picture or MetaFile, is stored 
as one or more graphics orders. In all cases, drawing orders are contained in 
graphics segments either in PS segment store as part of a retained picture or in a 
MetaFile. A drawing order is the smallest complete unit of a graphics segment. 

Orders have a 1-byte order code and can be classified into the following groups, 
based on order length: 

• Fixed 1-Byte Orders. 

• Fixed 2-Byte Orders. 

• Long Orders. 

• Extended Orders. 


Fixed 1-Byfe Orders 

There are only two 1-byte orders. They are: 

ByteO = 0x00 GNOP1 (No-Operation); and 

ByteO = OxFF GESD (End of Symbol Definition). 

GESD applies to outline font character definitions only. An order is a 1-byte order 
if its order code is either 0x00 or OxFF. 
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Fixed 2~Bjte Orders 

Fixed 2-byte orders have the form: 

ByteO = order code with bit7=0 & bit 3=1 (i.e. Oxxxlxxx) 

Bytel = order data 

An order is a 2-byte order if the order code has bit7=0 and bit3=l. Examples of 
2-byte orders are: 

ByteO = 0x18 GSLT (Set Line Type) 

Bytel = 0x01 dotted 

ByteO = 0x68 GEAR (Begin Airea) 

Bytel = 0x40 draw boundary using alternate mode fill 


Long Orders 

These are orders of variable length between 3 and 257 bytes. Long orders have the 
form: 

ByteO = order code (not 1-byte, 2-byte or extended) 

Bytel = length of following data (£255) 

Byte2+ order data 

An order is a long order if the order code is neither a 1-byte nor an extended order 
code, and does not satisfy the criteria for a 2-byte order (i.e., order code is not 0x00, 
OxFF, OxFE and bit7=l or bit3=0). Examples of long orders are: 

ByteO = 0x81 GCLINE (Line at Current Position) 

Bytel = length of following data 

Byte2+ xy coordinate points 

ByteO = 0xD6 GBBLT (WC BitBlt) 

Bytel = length of following data 
Byte2-n Flags, mix, source bitmap, etc. 

ByteO = 0xD5 Escape (used in MetaFile only) 

Bytel = length of following data 
Byte2 = 0x80 Type = Registered 
ByteS = 0x01 (Set Pel) 

Byte4-n order data 
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B}rfceO = OxD5 Escape (used in MetaFile only) 

Bytel = length of following data 
Byte2 = 0x80 Type = Registered 
Byte3 = 0x02 (BitBlt) 

Byte4-n order data 

MetaFiles use long escape orders (e.g, set pel above) to record functions not defined 
by the interchange architecture (see chapter 11). 

Extended Orders 

These are orders that have a variable length of up to 64K bytes. They are 
identified by a unique order code (OxFE) followed by an order qualifier, providing 
the real order code, and a 2-byte length field. Note that bytes 2 and 3 of the order, 
which contain the 2-byte length field, have the high order byte first; this is the 
reverse of the normal 2-byte numerical representation. Extended orders have the 
form: 


ByteO = OxFE (extended order) 

Bytel = order qualifier (i.e., actual order code) 

Byte2 = length of following data (MS byte) 

Byte3 = length of following data (LS byte) 

Byte4-n order data 

An order is an extended order if its order code is OxFE. Examples of extended 
orders are: 

ByteO = OxFE (extended order) 

Bytel = 0xC3 GCHST (Character String at Given Position) 

Byte2 = length (MS byte) 

Byte3 = length (LS byte) 

Byte4-n xy position, character string 


ByteO = OxFE (extended order) 

Bytel = 0x83 GCCHST (Character String at Current Position) 
Byte2 = length (MS byte) 

Byte3 = length (LS byte) 

Byte4-n character string 
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ByteO = OxFE (extended order) 

Bytel = OxFO GCHSTE (Character String Extended at Given 
Position) 

Byte2 = length (MS byte) 

ByteS = length (LS byte) 

Byte4-n xy position, flags, rectangle, string, increments, etc. 

ByteO = OxFE (extended order) 

Bytel = OxBO GCCHSTE (Character String Extended at Current 
Position) 

Byte2 = length (MS byte) 

Byte3 = length (LS byte) 

Byte4-n flags, rectangle, string, increments, etc. 

ByteO = OxFE (extended order) 

Bytel = 0xD5 Escape 
Byte2 = length (MS byte) 

Byte 3 = length (LS byte) 

Byte4 = 0x00 Unregistered 

ByteS = 0x01 MetaFile Create Logical Color Table 
Byte6-n order data 

MetaFiles use extended escape orders (e.g., Create Logical Color Table above) to 
record functions not supported by the interchange architecture and to record 
changes to the environment or resources that occur in the picture data (see chapter 
11 ). 


Order Buffers 


Although normally used within elements and segments, order buffers can be 
transferred between application memory and the presentation space using: 

GpiPutData; and 

GpiGetData. 

GpiPutData can be used to draw a buffer of orders, store them in a retained 
segment, or both, depending on the drawing mode. The buffer need not contain a 
whole number of complete orders. If there is an incomplete order at the end of the 
bufier, then this will be returned to the application unprocessed enabling the 
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application to concatenate this in front of the subsequent data. GpiGetData is used 
to retrieve a buffer of orders from a retained segment. Like GpiPutData, the 
returned data may not contain a whole number of complete orders. 


ELEMENTS 


An element is the smallest editable unit of a graphics segment and consists of 
either a single order, or, one or more complete orders within an element bracket. 
For example: 

GBEL (Begin Element); 

GPSTM (push and Set Model Transform); 

GCALLS (Call Segment); 

GPOP (Pop); and 

GEEL (End Element). 

The purpose of the Begin and End Element is to bracket together a group of related 
orders enabling them to be edited as a single entity in a retained segment. For 
example, GpiCallSegmentMatrix generates the entire sequence of orders shown 
above. As this sequence of orders is generated by a single GPI function, they form 
a single element, which can, for example, be subsequently deleted by a single 
GpiBeleteElement call. 

Each element has a type and description (which can be null). For elements 
consisting of a single order, these are implicit. For elements defined by a Begin 
Element—End Element bracket, these form part of the Begin Element order. 
Elements may be generated by the system, as described above, or an application 
may define its own. Application defined elements should specify a type value in 
the range 0x81000000-0xFFFFFFFF. Values outside this range are reserved for 
system use. 

Functions similar to GpiPutData and GpiGetData exist for setting and retriev¬ 
ing an order buffer containing a single complete element. These are: 

GpiElement; and 

GpiQueryElement. 


GRAPHICS SEGMENTS 

All pictures stored in a retained PS segment store or a MetaFile are constructed 
from one or more graphics segments, with each segment containing one or more 
elements (or orders). A graphics segment is created by issuing the GPI functions 
required to define the contents of the segment between: 

GpiOpenSegment; and 

GpiCloseSegment. 
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A segment may be retained (i.e., stored in retained PS segment store) or non-re- 
tained (i.e., the primitives are drawn as it is defined and immediately discarded) 
depending on drawing mode (see below). 

The structure of a graphics segment structure is illustrated in Figure 9-1. Each 
segment has a segment id, a number of segment attributes, an (optional) internal 
prolog, and the segment body containing the elements (i.e., groups of primitive 
drawing and attribute orders). 

Segments with no internal prolog have implicit viewing and segment transforms 
of identity. An internal prolog is added, as necessary, to a retained segment by 
GpiSetSegmentTransformMatrix. The prolog is termed an ‘internal prolog’ be¬ 
cause it is not visible to an application and cannot be edited with the elements in 
the body of a retained segment. The internal prolog will, however, be visible as a 
normal prolog (complete with prolog segment attribute and end prolog order) if the 
segment is recorded in a MetaFile. Application defined prologs (with end prolog 
orders and prolog segment attribute as described in the IBM Graphics Architec¬ 
ture Reference) are not currently supported by the GPI except within MetaFiles. 
An End Prolog order passed with GpiPutData, for example, will be treated as a 
No-Op. 


First Element- 


Segment id 


Segment Attributes 

ATTR_DETE CTAB LE 

ATTR„VISIBLE 

ATTR_CHAXNED 

ATTR DYNAMIC 

ATTR_FASTCHAXN 

ATTR_PRO P_DETECTABLE 

ATTR_PR0P VISIBLE 


Viewing Transform Matrix 


Segment (Model) Transform 
Matrix 


Graphics Elements (orders) 


may include GCALLS - 
(call to another segment) 


(— Internal 
Prolog 


Figure 9.1 Graphics Segment Structure. 
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The segment transform can be modified and queried using 
GpiSetSegmentTransformMatrix and GpiQuerySegmentTransformMatrix but 
currently, the viewing transform, once established for a retained segment, cannot 
subsequently be modified or queried at all for that segment. 

The function CreateRetainedSegment in Figure 9-2 illustrates the creation of a 
retained (chained) graphics segment followed by a draw chain operation. 


/* crretseg.c */ 

BOOL CreateRetainedSegment(HPS hps, LONG ISegld) 


/* Create a retained (chained) graphics segment (which is appended to the 
/* chain) and draw the chain. It is assumed that the PS drawing mode may not 
/* be DM_RETAIN on entry. 

/* 

/* inputs: hps PS handle 
/* ISegld Segment ID 

/* 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


^define SEGCHARS “Retained Segment Characters” 
^define NSEGCHARS (LONG)(sizeof(SEGCHARS)-1) 


BOOL fRet 

BOOL fRetS = FALSE 

POINTL ptlPoint 


fRet = GpiSetDrawingMode( hps 

, DM_RETAIN 
); 


/* 

BOOL return 

code 

*/ 

/* 

BOOL return 

code 

*/ 

/* 

coordinate 

poi nt 

*/ 

/* 

set drawing 

mode to 

retain */ 

/* 

-PS handle 


*/ 

/* 

-mode = ret 

ai n 

*/ 


if (fRet) 

fRet = GpiSetlnitialSegmentAttrs 


/* set chained initial 
( hps /* -PS handle 

, ATTR_CHAINED /* -attribute 
, ATTR_0N /* -value 
); 


seg attr */ 
*/ 
*/ 
*/ 


if (fRet) 

fRet = fRetS = GpiOpenSegment( hps 

, ISegld 


); 


/* open segment 
/* -PS handle 
/* -segment id 


*/ 

*/ 

*/ 


ptlPoint.x = 100L; 
ptlPoint.y = 100L; 
if (fRet) 

fRet = (BOOL)GpiCharStringAt( hps 

, &ptlPoint 
, NSEGCHARS 
, SEGCHARS 
); 


if (fRetS) 

fRet = GpiCloseSegment(hps) && fRet; 
if (fRet) 

fRet = GpiDrawChain(hps) ; 
return(fRet) ; 


/* draw to segment 


/* close segment 


/* draw chain 


*/ 


*/ 

*/ 


Figure 9.2 CreateRetainedSegment Function. 
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CHAINED MB BAILED SEGMENTS 

The GPI allows the entire graphics picture to be stored in, and redrawn from, a 
Normal-PS segment store. This is called retained graphics/ The GPI retained 
graphics model defines a picture as a single chain of one or more retained graphics 
segments. A segment is chained if its ATTR_CHAINED segment attribute is set. 
A chained segment is sometimes called a root segment. Unchained retained 
segments may also exist and may be drawn individually by the application using 
GpiDrawSegment, called from other chained or unchained segments, or called 
directly by an application using GpiCallSegmentMatrix. 

A typical retained segment store structure containing both root (chained) and 
called (unchained) segments is shown in Figure 9-3, which also illustrates the 
segment drawing functions: 

GpiDrawChain; 

GpiDrawFrom; and 

GpiDrawSegment. 


RETAINED SEGMENT STORE 

SEGMENT CHAIN CALLED SEGMENTS 

(ROOT SEGMENTS) 



Figure 9.3 Retained Segment Store Example. 
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GpiDrawChain draws the entire segment chain including all segments called 
directly and indirectly from the root segments. GpiDrawFrom draws a range of 
segments in the chain from a specified first to a specified last segment. All 
segments called directly and indirectly from the drawn root segments are also 
drawn. The first segment must be in the chain and neither first nor last segment 
id may be specified as zero. If the specified last segment does not appear 
between the first segment and the end of the chain, it is not an error; drawing 
continues to the end of the chain. GpiDrawSegment draws a single specified 
segment including all segments called directly and indirectly from it. The 
specified segment may be chained or unchained but its id may not be specified 
as zero. 

When using GpiDrawFrom or GpiDrawChain, the position of a root segment in 
the chain determines whether it is drawn on top of, or beneath the other segments 
in the chain and is called the Segment Priority. The segment drawn last in the 
chain is displayed on top of all the others and therefore has highest priority. Each 
new segment that is created is added to the end of the chain. The priority of a 
segment can be queried and changed using: 

GpiQuerySegmentPriority; and 

GpiSetSegmentPriority. 

GpiQuerySegmentPriority specifies a reference segment id together with either 
LOWERJPRI or HIGHER JPRI and the function returns the id of the segment 
immediately before or immediately after the reference segment (or zero if the 
reference segment is at the start or end of the chain). 

GpiSetSegmentPriority specifies the id of both a target and reference segment 
and specifies either LOWER_PRI or HIGHER_PRI to indicate where the target 
should be positioned relative to (i.e., immediately before or immediately after) the 
reference segment. If LOWER_PRI is specified with a reference segment id of zero, 
then the target is given highest priority in the chain (i.e., positioned at the end of 
the chain). If HIGHER_PRX is specified with a reference segment id of a zero, then 
the target is given lowest priority in the chain (i.e., positioned at the start of the 
chain). 

The segment chain structure for a MetaFile is similar to that for segment store. 
The main difference is that called segments in an imported MetaFile may be 
chained or unchained (as permitted by the architecture) whereas those in the GPI 
PS segment store must be unchained. 


DRAWING MODES 

GPI primitive drawing and attribute functions are either drawn immediately, 
stored as elements in the currently open retained segment, or both, depending on 
the PS drawing mode (i.e., draw, retain, or draw and retain). Drawing mode is 
controlled by: 


GpiSetDrawingMode 
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which specifies the drawing mode for the PS as one of: 

DMJDRAW; 

DMJRETAIN; and 

DM_DRAWANDRETAIN. 

While these determine the actual drawing mode for chained segments, these 
modes are overridden for unchained segments and functions issued outside a 
segment bracket. Unchained segments (on the assumption that they will be called) 
are always constructed in retained mode regardless of current drawing mode. GPI 
functions issued outside a segment bracket are always drawn immediately, re¬ 
gardless of current drawing mode. 

In addition, a small number of functions totally ignore the drawing mode. These 
are always drawn immediately and never stored in a retained segment. They are: 

GpiPaintRegion; 

GpiBitBlt (but not GpiWCBBitBlt); 

GpiSetPel; and 

All WinDraw functions (e.g., WinDrawText). 


SEGMENT ATTRIBUTES 

Segments have a number of properties called segment attributes (see Figure 9-1) 
that each have a Boolean value of ATTR_ON or ATTR_OFF. In addition, the PS 
contains a set of 'initial segment attributes’ that determine the initial segment 
attribute values for a newly created segment at the time if is first opened. The 
'initial segment attributes’ of the PS can be set and queried using: 

GpiSetlnitialSegmentAttrs; and 

GpiQuerylnitialSegmentAttrs. 

The segment attributes of a specified retained segment can be set and queried 
using: 

GpiSetSegmentAttrs; and 
GpiQuery S egment Attrs. 

The segment attributes are as follows: 


ATTRJ3ETECTABLE 

The segment is enabled for the detection of retained correlation hits (see 
chapter 10). 
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ATTR_VISIBLE 

The segment is visible. 

ATTR_CHAINED 

The segment is chained. Setting or resetting this attribute for an existing retained 
segment causes the segment to be added to or removed from the segment chain. 

ATTR_DYNAMIC 

The segment is dynamic (see below). 

ATTR_FASTCHA!N 

The segment is fast chained. This is a performance hint allowing the system to 
omit the attribute reset that otherwise occurs at the start of each root segment as 
it is drawn. The ATTR_FASTCHAIN attribute applies to chained (root) segments 
drawn using GpiBrawChain and GpiDrawFrom. 

If fast chaining is specified then the application undertakes to set every attri¬ 
bute used within the segment to the required value before it is used. It is good 
practice to set fast chaining off for the first segment in the chain at least, or else 
issue GpiResetPS (to ensure that the attributes are reset) before each 
GpiBrawChain or GpiDrawFrom function call is issued. Failure to do this can give 
strange effects. For example, if all segments are fast chained with no reset 
performed, then one segment setting the model transform with some translation 
can cause the picture to move progressively across the screen (and eventually out 
of view) each time GpiBrawChain is issued. 

Note also that fast chaining does not guarantee that attributes will not be 
reset—it merely gives the system this option. In a future implementation, the fast 
chaining attribute could well be ignored such that attributes are always reset at 
the start of each root segment. This would still represent a valid implementation 
of the architecture. An application should therefore never rely on the inheritance 
of non-default attribute settings from one chained segment to another. 

ATTR_PROP_DETECTABLE 

The segment will propagate the ATTR_DETECTABLE attribute to any segment it 
calls. 

ATTR_PROP_VIS!BlE 

The segment will propagate the ATTR_VISIBLE attribute to any segment it calls. 


SEGMENTS WITH ZERO 10 

In general, every retained segment in segment store must have its own unique 
segment id. The one exception to this rule is for segments with an id of zero that 
can occur more than once in the segment chain. Whereas GpiOpenSegment 
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specifying a non-zero segment id will reopen any existing retained segment with 
that id, if the id is zero, a new segment will always be opened. Segments with zero 
id have the following restrictions: 

• They cannot be edited. 

• They must be chained. 

• They cannot have their segment transform set or queried. 

• They cannot have their segment attributes set or queried. 

• They cannot have their segment priority set or queried. 

• They cannot return a correlate hit. 

• They cannot be specified with GpiDrawSegment or GpiDrawFrom. 

Segments with a zero id can be drawn by GpiDrawChain or GpiDrawFrom as part 
of the segment chain and will contribute to boundary data. 

Any primitive or attribute functions issued outside a segment bracket when 
recording a MetaFile are recorded in the MetaFile as segments with an id of zero. 

The function SubpictureMetaFile (in chapter 11), for example, illustrates the 
use of GpiOpenSegment with a zero segment id for the purpose of setting the 
viewing transform matrix attribute before clearing the background rectangle. 

NDN-RETAINED SEGMENTS 

A non-retalned segment is a group of drawing primitive and attribute functions 
issued within a GpiOpenSegment - GpiCloseSegment bracket in DMJDRAW 
mode. Although not immediately apparent, there are certain advantages in main¬ 
taining this segment structure, even for non-retained drawing. 

• If the ATTR_FASTCHAIN initial segment attribute for the PS is not 
set, GpiOpenSegment will perform an implicit attribute reset opera¬ 
tion. 

• GpiOpenSegment allows the viewing transform matrix attribute to 
be initialized from the PS and the GpiCloseSegment causes it to be 
reset back to identity. 

• If the output is being recorded in a MetaFile, the non-retained 
segments (complete with segment id and attributes) will be recorded 
in the MetaFile. 

• Anon-retained picture constructed using named segments can easily 
be converted for retained operation in the future. 


DRAW CONTROLS 

The PS has a number of draw controls each with a Boolean value of DCTL_ON or 
BCTL_OFF. These can be set and queried using: 

GpiSetDrawControl 

GpiQueryDrawControl 




184 


OS/2 PRESENTATION MANAGER GPI 


The draw controls are as follows: 


DCTLJERA5E 

This causes an implicit erase to be performed before any GpiDrawSegment, 
GpiDrawFrom, or GpiDrawChain operation. 

DCTL_DSSPLAY 

This causes output to be visible on the device. If this control is not set, no output 
is displayed. GpiErase is unaffected by this attribute. 

BCTL_BOUNDARY 

This enables boundary accumulation (see chapter 10). 

DCTLJJYNAMIC 

This causes dynamic segments to be implicitly removed and redrawn around any 
GpiDrawFrom or GpiDrawChain operation (see below). 

DCTL_CORRELATE 

This enables correlation for GpiPutData, GpiElement, GpiPlayMetaFile and all 
non-retained drawing primitives. 


STOP DRAW 


Many GPI graphics drawing operations can take a considerable time to complete 
and should normally be performed on a separate thread from that used for 
message queue processing. For most GPI functions, it is invalid to use the same 
PS on more than one one thread simultaneously. The one exception to this is 
GpiSetStopDraw, which enables any of the following functions to be terminated 
(with a logged warning): 

GpiBrawSegment; 

GpiDr awF r om; 

GpiDrawChain; 

GpiDrawDynamics; 

GpiPlayMetaFile; and 

GpiPutData. 

A draw operation would normally be terminated (and perhaps restarted with 
different data) in response to an event on the message queue. A GpiSetStopDraw 
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request to set the 'stop draw' condition must be followed by a subsequent 
GpiSetStopDraw to clear this condition before further drawing can occur. A 
semaphore or some other synchronization mechanism will normally be required 
to s 3 mchronize setting and resetting the 'stop draw' state with stopping and 
restarting (drawing on a separate asynchronous thread. 


OYNAMiO SEGMENTS 

The dynamic segment attribute (ATTR_DYMAMIC) is provided for interactive 
retained segment operations, allowing segments on a display screen to be rapidly 
removed and redrawn without disturbing the underlying picture. Dynamic seg¬ 
ments are intended for such operations as dragging and rubber banding. 

The ATTRJDYNAMIC segment attribute applies only to chained segments and 
is ignored for unchained segments and segments drawn individually using 
GpiDrawSegment. Dynamic segments are not recorded in a MetaFile. A segment 
called directly or indirectly from a dynamic segment inherits the dynamic segment 
attribute. Dynamic segments have the following properties. 

Regardless of their position in the chain, dynamic segments are drawn last, on 
top of the remainder of the picture, with foreground mix of FM_XOR (i.e., exclu- 
sive-OR) mode and background mix of BM_LEAVEALONE (i.e., transparent). Mix 
values specified within the dynamic segments are ignored. 

Dynamic segments are drawn using GpiDrawDynamics and removed using 
GpiRemoveDynamics. Their contents must not be modified while drawn, even if 
not actually visible, or problems will arise during their removal. To modify their 
contents, they must be removed, updated, and then redrawn. GpiRemoveDynam¬ 
ics can specify a segment range, allowing removal to be restricted to only those 
segments affected by the update. If a range has been previously established by 
GpiRemoveDynamics, then GpiDrawDynamics redraws only this previously es¬ 
tablished range, otherwise it redraws all dynamic segments. The range is import¬ 
ant and must include all dynamic segments affected by the update, even if these 
are not actually visible. This range does not allow a subset of the dynamic 
segments to be visible; all dynamic segments (or none) must be visible after a draw 
operation. 

Dynamic segments are implicitly removed before, and replaced after, any 
GpiDrawFrom or GpiDrawChain if the DCTLJDYNAMIC draw control is set. The 
range established by GpiRemoveDynamics is ignored for this implicit redraw; all 
dynamic segments are redrawn. 

GpiDrawDynamics can be interrupted (and stopped) by issuing 
GpiSetStopDraw (SDW_OFF) on a different thread. This would apply if, for 
example, the current GpiDrawDynamics operation was invalidated by a new event 
on the message queue requiring a new update and redraw. Even if 
GpiDrawDynamics is stopped before completion, GpiRemoveDynamics will still 
remove the correct amount of dynamic segment data from the screen and no more. 
GpiRemoveDynamics (explicit or implicit) cannot be stopped using 
GpiSetStopDraw. 
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If the ATTR_FASTCHAIN attribute is used for the dynamic segments, it is 
important that the attributes (e.g., model transform matrix) are reset before 
processing these segments, either by issuing GpiResetPS or by ensuring the 
ATTR_FASTCHAIN segment attribute is reset at least for the first dynamic 
segment in the chain. 

Dynamic segments can be positioned anywhere in the segment chain but, for 
best performance, should be near the start of the chain. 


SEGMENT EDITING 

The GPI provides functions for editing the contents of existing retained segments. 
These allow deletion, insertion, and replacement of elements in the currently open 
retained segment. 

To assist editing, label elements with numerical label values can be used to mark 
reference points in the segment. A label element is similar to the segment tag 
element used for correlation (see chapter 10) and like the segment tag, produces 
no output to the device when drawn. Label elements are normally stored in the 
segment at creation time using: 

GpiLabel 

To edit an existing retained segment, the segment is reopened by specifying its id 
with: 


GpiOpenSegment 

Many segment editing operations use the element pointer. The element pointer 
starts at zero and increases by one for each element from the start of the segment. 
Elements can be replaced or inserted in the segment at the current element 
pointer position using any of the normal drawing primitive and attribute functions 
(including GpiBeginElement, GpiEndElement, and GpiElement). 

On reopening a segment, the element pointer position is reset to zero, which is 
immediately in front of the first element, and is incremented by one each time an 
element is inserted or replaced at the current element pointer. Note that when the 
current element pointer position is zero, which is before the first element, a new 
element can be inserted but not replaced. 

The element pointer value can be set and queried using: 

GpiSetElementPointer; 

GpiSetElementPointerAtLabel; 

GpiOffsetElementPointer; and 

GpiQueryElementPointer. 

Whether a new element is inserted, or replaces an existing element, is determined 
by the PS edit mode, which can be set to either SEGEMJNSERT which is the 
default, or SEGEM_REPLACE. The PS edit mode is set and queried using: 



GpiSetEditMode; and 
GpiQueryEditMode. 
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Functions also exist to delete the element at the current element pointer, all the 
elements in a given range (including the first and last in the range), and all the 
elements between two labels (excluding the labels). These are performed using: 

GpiBeleteElement; 

GpiDeleteElementRange; and 

GpiBeleteElementsBetweenLabels. 

The element type and description string can be queried for the element at the 
current element pointer position using: 

GpiQueryElementType 

Note that a segment with segment id of zero cannot be edited. 

An example of segment editing is illustrated by the function EditSegment in 
Figure 9-4. This opens a segment, replaces the first element, sets the element 
pointer to a label, and inserts two new elements. 


WHOLE SEGMENT EDITING FUNCTIONS 

In addition to the functions for editing the contents of individual segments and for 
modifying segment attributes, a number of whole segment editing functions exist, 
some of which have been mentioned earlier. Segments are created, reopened and 
closed using: 


GpiOpenSegment; and 
GpiCloseSegment. 

Segment priority is set and queried using: 

GpiSetSegmentPriority; and 
GpiQuerySegmentPriority. 

The identity of all existing segments in a given range can be queried using: 
GpiQuery S egmentNames 

Individual segments or a range of segments can be deleted using: 


GpiBeleteSegment; and 
GpiBeleteSegments. 
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/* editsegm.c */ 

BOOL EditSegment(HPS hps, LONG lSegld) 

{ 

/* Set drawing mode to DM_RETAIN, reopen the specified segment, edit it as */ 
/* described below and draw the chain. */ 

/* It is assumed that the PS drawing mode may not be DM_RETAIN on entry. */ 

/* */ 

/* The segment is edited as follows: */ 

/* Replace the first element with a Set Current Position (0CODE_GCSP) element.*/ 
/* Set the element pointer to label with value 6. */ 

/* Insert a Set Current Position (0C0DE_GSCP) element. */ 

/* Insert a Line at Current Position (0C0DE_GCLINE) element. */ 

/* */ 

/* inputs: hps PS handle */ 

/* lSegld Segment ID */ 

/* */ 

//define LBL6 6L 

BOOL fRet ; /* BOOL return code */ 

BOOL fRetS = FALSE ; /* BOOL return code */ 

POINTL ptlPoint ; /* coordinate point */ 

/* set drawing mode to retain */ 

fRet = GpiSetDrawingMode( hps /* -PS handle */ 

, DM_RETAIN /* -mode = retain */ 

); 

if (fRet) /* reopen segment */ 

fRet = fRetS = GpiOpenSegment( hps /* -PS handle */ 

, lSegld /* -segment id */ 

); 

if (fRet) /* set element pointer to 1 */ 

fRet = GpiSetElementPointer( hps /* -PS handle */ 

, 1L /* -element number */ 

); 

if (fRet) /* set edit mode to replace */ 

fRet = GpiSetEditMode( hps /* -PS handle */ 

, SEGEM_REPLACE /* -mode = replace */ 

); 

ptlPoint.x = 300L; 

ptlPoint.y = 300L; 

if (fRet) /* replace element by 0C0DE_GSCP */ 

fRet = GpiSetCurrentPosition( hps /* -PS handle */ 

, &ptlPoint /* -coordinate point */ 

); 

if (fRet) /* set element pointer at label */ 

fRet = GpiSetElementPointerAtLabel ( hps /* -PS handle */ 

, LBL6/* -label */ 

) ; 

if (fRet) /* set edit mode to insert */ 

fRet = Gpi SetEdi tMode ( hps /* -PS handle */ 

, SEGEM_INSERT /* -mode = insert */ 

); 


Figure 9.4 EditSegment Function. 
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ptlPoint.x = 200L; 

ptlPoint.y = 200L; 

if (fRet) /* insert 0C0DE_GSCP element */ 

fRet = GpiSetCurrentPosition( hps /* -PS handle */ 

, &ptlPoint /* -coordinate point */ 

); 

ptlPoint.x = OL; 

ptlPoint.y = 100L; 

if (fRet) /* insert 0C0DE_GCLINE element */ 

fRet =(BOOL)GpiLine( hps /* -PS handle */ 

, &ptlPoint /* -coordinate point */ 

); 

if (fRetS) /* close segment */ 

fRet = GpiCloseSegment(hps) && fRet; 

if (fRet) /* draw chain */ 

fRet = GpiDrawChain(hps ); 


return(fRet); 

Figure 9,4 (continued) 



10 


Correlation and Boundary Data Accumulation 


CORRELATION 


The correlation functions enable an application to define a rectangle, called the 
pick aperture, against which all drawing primitives (but not GpiErase) are com¬ 
pared for intersection. Their purpose is to enable an application, such as a graphics 
editor, to determine the primitive (or primitive group) a user has selected on the 
display screen by pointing and clicking (e.g., using a mouse and pointer). 

The pick aperture is defined in device independent coordinates in the PS Page. 
If a non-retained drawing primitive intersects the pick aperture then a hit 
(GPI_HITS) is returned for that primitive. For a non-retained primitive that does 
not intersect the pick aperture, no hit (GPI_OK) is returned. 

Correlation is also supported for retained graphics that provides special func¬ 
tions for performing correlation and identifying the location of any hits (i.e., 
position in segment, segment name, and segment call context). 

The pick aperture size, for both retained and non-retained correlation, is set and 
queried using: 

GpiSetPickApertureSize; and 
GpiQueryPickApertureSize. 


Non-Retainei Correlation 

Non-retained correlation is enabled and disabled using: 

GpiSetDrawControl(hps, DCTL_CORRELATE, 
DCTL_ON/DCTL_OFF) 
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and the pick aperture position is set and queried using: 
GpiSetPickAperturePosition; and 
GpiQueryPickAperturePosition. 

With the DCTL_CORRELATE draw control set, an individual drawing primitive 
(e.g., GpiLine), GpiPutData, GpiElement, or GpiPlayMetaFile will return 
GPIJHITS or GPIOK, depending on whether or not the output from the operation 
intersects the pick aperture, or GPI_ERROR if an error is detected. GpiErase will 
never return a correlate hit. 

Where the primitive is an area fill operation (e.g., GpiFullArc/DRO_FILL or 
GpiEndArea), a hit will be returned if the pick aperture lies partially or totally 
within the filled area. If the primitive is an unfilled figure (e.g., 
GpiFullAr<yDRO_OUTLINE), a hit will be returned only if the pick aperture 
intersects the figure boundary. Note that an area fill can return a correlate hit even 
if the AREABUNDLE pattern is set to no shading (i.e., PATSYM_NONSHADE), a 
line can return a hit even with line-type set to LINETYPE_INVISIBLE, and a hit 
can still be returned using mix values of FM_LEAVEALONE or 
BM_LEAVE ALONE. 

detained Correlation 

Special purpose functions exist to perform correlation on retained graphics seg¬ 
ments. These specify the pick aperture position and the target segment or seg¬ 
ments as parameters to the correlate request. The target can be an individual 
segment, part of the segment (picture) chain, or the complete chain. 

In addition, where multiple hits are returned from a single retained correlation 
operation, the segment tag attribute can be used by the application to distinguish 
between the different hits. 

Retained correlation is performed by processing the target segments exactly as 
if they were being drawn, but performing correlation rather than drawing. Re¬ 
tained correlation is performed using: 

GpiCorrelateChain; 

GpiCorrelateFrom; and 

GpiCorrelateSegment. 

GpiCorrelateChain performs correlation on the entire segment chain. 
GpiCorrelateFrom performs correlation starting from a specified segment and 
stopping at a different specified segment. If the stop’ segment is not found during 
the correlate operation, it is not an error, correlation continues to, and stops at, the 
end of the chain. GpiCorrelateSegment performs correlation on a single specified 
segment. 

Any retained correlation operation will also include all segments called directly 
or indirectly from the specified segments, provided the segment attribute and tag 
order values are set to enable correlation. 
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The segment tag attribute associates a numerical tag value (or pick identifier) 
with subsequent primitives in a retained segment for the purpose of retained 
correlation. GpiSetTag will cause a Set (or Push and Set) Pick Identifier element 
to be stored in the open segment at the current element pointer position. When a 
retained correlate hit is returned, the tag attribute value at the hit location is 
returned with the segment name to the application (see Figure 10-1). This enables 
an application to determine the position of the hit and to distinguish between 
different hits within the same segment. Multiple hits in the same segment with 
the same tag value are registered as a single hit. When the segment is drawn, the 
tag elements produce no output to the device. 

If the tag value is zero (the initial default) or a segment has a zero segment 
identifier, correlation is disabled. Correlation is also enabled or disabled by the 
segment attributes. For correlation to be enabled, either the ATTRJDETECT- 
ABLE segment attribute must be set or, if called from a detectable segment, the 
value of the ATTR_PROP_DETECTABLE segment attribute must be set for the 
calling segment. Correlation is not enabled for dynamic segments unless they are 
unchained and are therefore being drawn non-dynamically. The application can 
also specify whether correlation is required for only visible segments (i.e., those 
with their ATTR_VISIBLE segment attribute set), or for all segments as a param¬ 
eter to the correlation functions. 


GpiSetTag(hps, 0) —— —=■> 


GpiSetTag(hps ,4)—-— > 


GpiSetTag(hps ,2)—-> 


Retained Segment ^ 
id 3 22 (non-zero; 


Set Pick Identifiar(O) 
Order (GSPIK) 


Orders will not 
record correlate hits 


Sat Pick Identifier(4) 
Order (GSPIK) 


Orders will return 
correlate hits with 
seg id=22 s segtag=4 


Set Pick Identifier(2) 
Order (GSPIK) 


Orders will return 
correlate hits with 
seg id=22, segtag=2 


segment with id = 0 will not return correlate hits. 

Figure 10.1 Retained Segment Correlation. 
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As a called segment may be called multiple times, it must be possible to determine 
the calling context of any hit. The correlate information is returned, last hit first, in 
an array of 'segment identifier - primitive tag pairs. The application specifies both 
the maximum number of hits (Max Hits) and the maximum number of id/tag pairs 
to be returned for each hit (MaxDepth). The retained correlation functions also 
provide the number of hits returned identifying the size of the returned array. 
Unused id/tag pairs in the array are set to zero. The following are examples of 
returned correlate information for different values of MaxHits and MaxDepth. 


MaxHits 

= 1 MaxDepth = 

i 


0x0011 

Segment ID 

= 17 

LAST HIT 

0x0008 

Tag 

= 8 


MaxHits 

= 2 MaxDepth 

= 4 


0x0011 

Segment id 

= 17 (called segment) 

LAST HIT 

0x0008 

Tag 

= 8 


0x0013 

Segment ID 

= 19 (root segment) 


0x0006 

Tag 

= 6 


0x0000 

unused 



0x0000 

unused 



0x0000 

unused 



0x0000 

unused 



0x0019 

0x0005 

Segment id 

Tag 

= 25 (called segment) 

NEXT TO LAST HIT 
= 5 

0x0017 

Segment id 

= 23 (called segment) 


0x0004 

Tag 

= 4 


0x0013 

Segment id 

= 19 (called segment) 


0x0003 

Tag 

= 3 


0x0020 

Segment id 

= 32 (called or root segment) 

0x0002 

Tag 

= 2 
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BOUNDARY ACCUMULATION 

Boundary accumulation enables the bounding rectangle of all drawing (excluding 
GpiErase) to be accumulated and returned in model space. The bounding rectangle 
is useful for 'scale to fit’ sub-picturing operations (see chapter 11), and for perform¬ 
ing optimizations and avoiding coordinate overflow (see chapter 7). Boundary 
accumulation is enabled and disabled using: 

GpiSetDrawControl (hps, DCTLJBOUNDARY, 
DCTL_ON/DCTL_OFF) 

and the boundary rectangle is queried and reset using: 

GpiQueryBoundaryData; and 
GpiResetBoundaryData. 

The rectangle returned from GpiQueryBoundaryData is inclusive at all bound¬ 
aries (i.e., all rectangle coordinates are inside the rectangle) and the reset value, 
or null boundary rectangle, has a negative width and height. 


i.e., 

xLeft 

= 0x07FFFFFF 


yBottom 

= 0x07FFFFFF 


xRight 

= OxF8000000 


yTop 

= 0xF8000000 


Boundary data is, of course, also reset by GpiResetPS, GpiSetPS, and 
GpiPlayMetaFile with the appropriate reset options. 
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MetaFiles 


The MetaFile functions enable Gpi graphics pictures to be transferred between a 
Presentation Space and a MetaFile, allowing picture interchange between users 
and applications. One application that exploits the MetaFile interchange capabil¬ 
ities is the OS/2 Clipboard. 

A MetaFile represents a ‘snapshot’ GPI graphics picture rather than an ani¬ 
mated sequence. MetaFiles may be stored as disk files, as data in application 
memory, or by the system as memory MetaFiles. 

THE METAFILE FUNCTIONS 

A MetaFile is initially created by issuing GPI calls to a PS associated with a DC 
of type OD_METAFILE or OD_METAFlLE_NOQUERY. This records (or accumu¬ 
lates) the picture in memory. When DevCloseDC is issued to close the MetaFile 
DC, the MetaFile is detached from the PS, and established as a memory MetaFile. 
DevCloseDC returns the handle of the newly created memory MetaFile to the 
application. A memory MetaFile can be saved to disk and deleted using 
GpiSaveMetaFile, or deleted without saving using GpiDeleteMetaFile. MetaFile 
creation, as described above, is illustrated by the function RecordMetafile in 
Figure 11-1, which also illustrates the use of GpiSaveMetaFile to save the memory 
MetaFile to disk. 

If a MetaFile has previously been saved as a disk file, it can be loaded from disk 
to re-create a new memory MetaFile using GpiLoadMetaFile. 

If a MetaFile has previously been saved as data in application memory, it can be 
used to re-create a new Memory MetaFile by opening and closing a MetaFile DC 
and using GpiSetMetaFileBits to transfer the data to this new MetaFile. This is 
illustrated by the function CreateMetaFile in Figure 11-2. Note that when using 
GpiSetMetaFileBits, it is not necessary, to transfer all the data in a single 
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operation. The offset and length parameters enable it to be issued multiple times 
to transfer the data in blocks, one buffer at a time. 

To transfer data from a MetaFile to application memory, GpiQueryMetaFile 
Length can be used to determine the size of the MetaFile and, having allocated 
sufficient memory, GpiQueryMetaFileBits can be used to transfer the data. Like 
GpiSetMetaFileBits, the offset and length parameters enable this function to be 
issued multiple times to transfer the data in blocks, one buffer at a time. 

A memory MetaFile may be drawn to a PS using GpiPlayMetaFile described 
below. 


SPiPLAYMETAFILE 

A MetaFile can be displayed as a normal non-retained picture by playing it to a PS 
in DM_DRAW mode, or it can be transferred to retained segment store using 
DM_RETAIN or DM_DRAWANDRETAIN mode. It can also be recorded in another 
MetaFile by playing it to a PS associated with a MetaFile DC. 

An array of options is available for use with GpiPlayMetaFile. Most of these 
control whether the resource and environment information in the MetaFile is 
ignored or is used to modify the presentation space. The main exceptions to this 
are the PMF__RESET and PMF_SUPPRESS options. 

GpiPlayMetaFile, with the combination of options that most accurately re-cre¬ 
ates the original MetaFile picture (with a non-realizable color table), is illustrated 
by the function PlayMetaFile in Figure 11-3. The GpiPlayMetaFile options are as 
follows: 

PMF_SEGBAS£ 

This is currently reserved and should be specified as zero. 

PMF_LOADTYPE 

This may be specified as one of the following: 

LT_DEFAULT (i.e., LT_NOMODIFY) causes the viewing 
transform matrix values in the MetaFile segments to be ignored 
and the value in the PS to be preserved and used for each 
graphics segment opened during GpiPlayMetaFile. It also 
causes any graphics field definitions in the MetaFile to be 
ignored. 

LT_ORIGINALVIEW causes the viewing transform matrix 
values in the MetaFile segments to be used for the correspond¬ 
ing graphics segments opened during by GpiPlayMetaFile. 
With this option, the graphics field definition in the MetaFile is 
used to update the graphics field in the PS. 
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PMF_RESOLVE 

This is currently reserved and should be specified as zero. 

PMF_LCSDS 

This may be specified as one of the following: 

LC_DEFAULT (i.e., LC_NOLOAD) causes the logical font 
and bitmap id (or lcid) pattern resources defined in the MetaFile 
to be ignored and those in the PS to be preserved and used for 
displaying the MetaFile picture. This option is applicable if the 
required fonts and bitmap patterns are already available in the 
PS. 

LC_LOADDISC causes the logical font and bitmap id (or lcid) 
pattern resources defined in the MetaFile to be loaded into the 
PS, replacing any existing PS set ids with the same value, and 
used for displaying the MetaFile picture. 


PMF_RESET 

This may be specified as one of the following: 

RES_DEFAULT (i.e., RES_NORESET) plays the MetaFile 
normally without performing a reset. 

RES_RESET causes the page units, page size, device trans¬ 
form, and default viewing transform to be set to the values 
defined in the MetaFile, and the PS to be reset with the equiv¬ 
alent of a GpiResetPS (GRES_ALL) function. This option is 
equivalent to creating a new PS with page units, page size, and 
default viewing transform identical to those defined in the 
MetaFile. This function is useful because it is not possible to 
determine the MetaFile page units, and so forth, in advance of 
GpiPlayMetaFile in order to specify these values on 
GpiCreatePS. 


PMF_SUPPRES$ 

This may be specified as one of the following: 

SUPJ3EFAULT (i.e., SUP_NOSUPPRESS) plays the MetaF¬ 
ile normally without suppressing drawing. 

SUP_SUPPRESS is intended for use with the RES_RESET 
option. These two options together enable the PS to be reset as 
described for RES_RESET without processing the remainder of 
the MetaFile resources or performing any drawing. The appli- 
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cation may then modify the PS environment and resources as 
required (e.g., by issuing GpiSetDefaultViewMatrix to scale the 
picture or GpiCreateLogColorTable to load the color table) and 
then play the MetaFile a second time without the RES_RESET 
and SUP_SUPPRESS options. This then displays the MetaFile 
using the modified environment and resources. This is 
illustrated by the function PlayMetaFile_Modify in Figure 11-4. 
This particular example reverses the PS background and fore¬ 
ground colors to display the MetaFile with a black background. 
This might be used for displaying a MetaFile converted from a 
PIF file for example. 


PMF.COLORTABLES 

This may be specified as one of the following: 

CTABJ3EFAULT (i.e, CTAB_NOMODIFY) causes the logi¬ 
cal color table defined in the MetaFile to be ignored and the 
color table in the PS to be preserved and used for displaying the 
MetaFile. 

CTAB_REPLACE causes the logical color table defined in the 
MetaFile to be loaded, replacing the existing color table in the 
PS. The PS color table is not reset by this option and existing 
PS color table entries not defined by the MetaFile are unmodi¬ 
fied. This option therefore enables an application to use the 
MetaFile to append to an existing application defined color 
table and then use this modified color table for displaying the 
MetaFile picture. 

PMF_C0LOREALIZABLE 

This may be specified as one of the following: 

CREA_DEFAULT (i.e., CREA NOREALIZE) causes the color 
table defined in the MetaFile to be loaded into the PS without 
its realize option set. This is the normal value of this option. 
Most MetaFiles do not contain realizable color tables. 

CREA_REALIZE is a no-op and should not be used. 

CREA_DOREALIZE (3L) was added by a 1.2 Corrective Ser¬ 
vice Diskette (and included in 1.3) together with support for 
GpiRealizeColorTable and gray scale changes in the display 
driver for the 8514/A display adapter. This will load the color 
table defined in the MetaFile as a realizable color table and 
realize it (effectively performing GpiRealizeColorTable) before 
playing the remainder of the MetaFile. It is the responsibility 
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of the application to subsequently issue GpiUnrealizeColorT- 
able at the appropriate time. Note that the CRE_DOREALIZE 
constant is not defined in the 1.2 header files. 


PMF_DEFAUILTS 

This may be specified as one of the following: 

BDEF_DEFAULT (i.e., DDEF IGNORE) causes default at¬ 
tributes defined in the MetaFile to be ignored and those in the 
PS to be preserved and used for displaying the MetaFile picture. 

DDEF_LOADDISC causes default attributes defined in the 
MetaFile to be set in the PS, replacing existing default attribute 
settings. 


METAFILE PRINTING AND METAFILE TO METAFILE RECORDING 


As explained above, the SUP_SUPPRESS option is useful for allowing application 
intervention between PS initialization and playing the remainder of the MetaFile. 
If, however, the RES_RESET option is required when playing a MetaFile to a PS 
associated with an OD_QUEUED/PM_Q_STD printer or MetaFile DC, use of the 
SUP_SUPPRESS option is essential (RES_RESET might be required, for exam¬ 
ple, to ensure that the MetaFile is printed or recorded with its original PS page 
units and size). Any attempt to issue GpiPlayMetaFile with RES_RESET after 
GpiAssociate with these DC types, is interpreted as an attempt to change the page 
units, which is invalid. An error will be returned and a PMERR_NO_METAF- 
ILEHANDLE or PMERRJNCOMPATIBLEJV1ETAFILE error will be logged. If 
the RESJRESET and SUP SUPPRESS options are used, they must, therefore, be 
issued before GpiAssociate. This is illustrated by the function PrintMetaFile in 
Figure 11-5. This restriction applies only if the target is a MetaFile DC or an 
OD_QUEUED DC with data type PM_Q_STD. 


SCALING A METAFILE TO FIT AN OUTPUT AREA 

A common requirement is to scale a MetaFile to fit an output area. This is 
accomplished by playing the MetaFile initially without displaying it to accumulate 
the boundary data, and then using the boundary data to define the required 
transform. This is illustrated by the function ScaleMetaFile in Figure 11-6, which 
scales the MetaFile to fit any specified rectangle (although typically the full screen 
or form size) in the PS page. 
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DISPLAYING A METAFILE AS A SUB PICTURE 

Another common requirement is that of displaying a MetaFile as a sub-picture of 
an existing picture. This is illustrated by the function SubpictureMetaFile in 
Figure 11-7, which is very similar to the function ScaleMetafile. The MetaFile is 
first played without displaying it to accumulate boundary data and the boundary 
data is then used to determine the required transform matrix. As this transform 
will vary during drawing of the combined picture, a picture rather than a PS 
environment attribute should be used. The viewing transform matrix is therefore 
used in place of the default viewing transform used above by ScaleMetafile. The 
advantage of this is that it enables the combined picture and sub-picture to be 
recorded in a new MetaFile, if required, without violating the MetaFile inter¬ 
change architecture. 

Note that SubpictureMetaFile enables the default viewing transform to be used 
for scrolling and scaling the original picture without affecting the position and size 
of the sub-picture. If it is a requirement to scroll and scale the sub-picture together 
with the original picture (using the default viewing transform) then this is easily 
accomplished by removing the GpiConvert function, effectively causing the target 
rectangle to be defined in default page coordinates rather than page coordinates. 

Unfortunately, the function SubpictureMetaFile as illustrated does not cur¬ 
rently work correctly with IBM OS/2 version 1.2. (but this is corrected by 1.3). On 
1.2 it is necessary to replace GpiSetViewingTransformMatrix (TRANSFORM_RE- 
PLACE) by GpiSetDefaultViewMatrix (TRANSFORM_PREEMPT). This will ac¬ 
tually work for all versions but is not ideal for the reasons explained above. 


METAFILE RESTRICTIONS AND ESCAPE ORDERS 

The internal format of a MetaFile provides a definition of the environment and 
resources, followed by the graphics segments containing orders defining the 
picture content (see the IBM Graphics Architecture Reference, Document Refer¬ 
ence, and OS/2 Programming Reference manuals). 

This 'snapshot’ representation of the graphics picture is not ideally suited to 
handling changes in environment and resources that occur during picture draw¬ 
ing, hence the distinction between PS environment/resources and picture func¬ 
tions discussed in chapter 1. As a consequence of this, certain rules exist for the 
creation of valid (i.e., SAA conforming) MetaFiles. When recording a MetaFile, 
some invalid functions will affect the integrity of the MetaFile picture, some will 
return an error, some will be ignored, and some will be recorded as MetaFile 
escape orders. A MetaFile escape order is not the same as a recorded DevEscape 
function, although the latter is one of a number of functions that can be recorded 
in a MetaFile escape order. MetaFiles containing MetaFile escape orders will 
generally interchange successfully with other OS/2 Presentation Manager sys¬ 
tems but attempts to interchange them with other products that conform to the 
same (SAA) interchange architecture may fail because the MetaFile escape orders 
will not be recognized. 
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In general, any change to the PS environment or resources after the start of the 
picture will be recorded as a MetaFile escape order. The picture start occurs when 
the first GpiOpenSegment, drawing primitive, or primitive attribute function is 
issued. 

The rules for creating a valid MetaFile are as follows: 

1. Page units and dimensions appear only once in a MetaFile and may 
not be altered after the first association of a PS and MetaFile DC. Any 
attempt to issue GpiSetPS or GpiAssociate to associate the MetaFile 
DC with a PS with different page units and/or size after the picture 
start will return an error. The page units and size stored in the 
MetaFile are specified for the PS either at creation time or the last 
GpiSetPS (or GpiPlayMetaFile with option RES_RESET) prior to 
association with the MetaFile DC. Any modifications to page units/de¬ 
vice transform made using GpiSetPageViewport are ignored for the 
purpose of MetaFile creation, even if performed before association 
with the MetaFile DC. 

Note that use of GpiAssociate to disassociate the MetaFile DC from its 
PS and associate it with another PS is valid so long as the PS page 
units and size of the new PS are identical to those already recorded in 
the MetaFile. 

2. Default viewing transform forms part of the MetaFile environment 
information and should therefore be established before any drawing 
occurs. If issued after the picture start GpiSetDefaultViewMatrix will 
be recorded as a MetaFile escape order. 

3. WinDrawText and similar WinDraw functions are intended only for 
output to display devices in non-retained mode. Such calls directed at 
a PS associated with a MetaFile DC will be ignored and not recorded 
in the MetaFile. 

4. GpiBitBlt, GpiSetPel, and GpiPaintRegion are intended for non-re¬ 
tained use only. These functions, if issued during MetaFile recording, 
are recorded as MetaFile escape orders. Note that GpiWCBitBlt is 
supported by the MetaFile architecture and may be used for BitBlt 
operations without producing MetaFile escape orders. 

5. A valid MetaFile has no means of recording the graphics field. Graph¬ 
ics field should therefore be set to no clipping (i.e., the default) for the 
duration of MetaFile recording, otherwise GpiSetGraphicsField will 
be recorded as a MetaFile escape order. 

6. Color tables form part of the MetaFile resources and should therefore 
be established before any drawing occurs. If issued after the picture 
start, GpiCreateLogColorTable will be recorded as a MetaFile escape 
order. 

7. Default attributes form part of the MetaFile environment information 
and should therefore be established before any drawing occurs. If 
issued after the picture start, any of the following functions will be 
recorded as MetaFile escape orders: 
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GpiSetDefAttrs; 

GpiSetDefViewingLimits; 

GpiSetDefTag; and 

GpiSetDefArcParams. 

8. A valid MetaFile has no means of recording the clip region. Clip region 
should therefore be set to no clipping (i.e., the default) for the duration 
of MetaFile recording, otherwise any of the following functions will be 
recorded as MetaFile escape orders: 

GpiSetClipRegion; 

GpiExcludeClipRectangle; 

GpilntersectClipRectangle; and 

GpiOffsetClipRegion. 

9. The draw control DCTL__DISPLAY must be set (to DCTL_ON) for the 
duration of MetaFile recording. If the draw control is set to 
DCTL_OFF during any drawing, or if GpiSetDrawControl is used to 
modify the DCTL_DISPLAY draw control after drawing has started, 
this is recorded as a MetaFile escape order. 

10. Logical font and bitmap ids form part of the MetaFile resources. These 
are defined using GpiCreateLogFont and GpiSetBitmapId either be¬ 
fore any drawing occurs or incrementally during drawing as they they 
are required. GpiDeleteSetld must not, however, be used to delete any 
ids until after the PS and DC are disassociated, or, in the case of a 
Micro-PS, should not be used at all (i.e., the system should be left to 
delete the set ids when the PS and DC are destroyed). Any of these 
functions, when used in an incorrect manner, are recorded as MetaFile 
escape orders. 

11. Bitmaps are used both as area fill patterns and as the source of BitBlt 
operations and therefore form part of the MetaFile resources. These 
should be loaded (or created) before any drawing occurs or may be 
added incrementally during drawing as they are required. 
GpiDeleteBitmap should not, however, be used to delete any bitmap 
before all required bitmaps have been created and bitmaps must not 
be modified during drawing. If bitmaps are deleted prematurely or 
modified during drawing, then incorrect data may be recorded in the 
MetaFile. 

12. None of the following functions should be issued. If issued, they will be 
recorded as MetaFile escape orders. 

GpiErase; 

GpiResetPS; 

GpiSetCp; 
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GpiSavePS; and 

GpiRestorePS. 

13. DevEscape calls with system escape codes in the range 8150-24449 
and non-system escape codes in the range 40960-57343 are recorded 
as MetaFile escape orders (note that for PM_Q_STD print files, the 
corresponding ranges are 16300-32599 and 49152-65535 respectively). 
Other DevEscapes may be passed to the display driver or ignored, 
depending on the value of the individual escape code. 

14. Only a limited range of foreground and background mix values should 
be used. These are: 

FMJ3EFAULT; 

FM_OR; 

FM_OVERPAINT; 

FM_LEAVE ALONE; 

BMJ3EFAULT; 

BM_OVERPAINT; and 
BM_LEAVE ALONE. 

Other mix values will be recorded and will interchange successfully 
with other OS/2 systems but may not be understood if interchanged 
with other products conforming to the same interchange architecture. 

15. Match numbers (i.e., the IMatch field in the FATTRS structure) should 
not be used for font creation when recording a MetaFile. Match 
numbers are not recorded in the MetaFile. 

16. Duplicate segment ids (other than zero) are invalid in a MetaFile. 
GpiDrawChain, GpiDrawFrom, and GpiDrawSegment should not be 
used to draw the same retained root segments more than once when 
recording a MetaFile. Likewise, GpiOpenSegment should not be used 
to open a new non-retained segment with a previously used non-zero 
segment id. A MetaFile containing segments with duplicate ids (other 
than zero) may return an error when subsequently played. 

17. Care must be taken when creating MetaFiles on one device for inter¬ 
change with another. For example, whereas an 8514/A display driver 
can support a color table (and color attributes) with up to 256 indices, 
most other drivers can support only 64 (as returned by the 
DevQueryCaps CAP8_COLOR_INDEX element). Exploiting the full 
color capabilities of the 8514/A driver will therefore produce a MetaF¬ 
ile that will not interchange successfully with a system using a VGA 
for example. 
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PIF FILES am PICTURE FUHCTIOH CALLS 

The PIF, or Picture Interchange File format, is an earlier IBM interchange format 
that existed before the MetaFile architecture was established. PIF format resem¬ 
bles that of a MetaFile and the Picture Utilities (picichg, picshow, and picprint) 
enable an end user to convert files from PIF to MetaFile format, and to display and 
print both PIF files and MetaFiles. In addition, the Picture function calls Piclchg 
and PicPrint allow equivalent PIF to MetaFile conversion and printing operations 
to be accessed as application function calls. 

PicPrint includes a parameter string, equivalent to the print queue processor 
parameters on DevOpenDC. Although PicPrint provides a simpler method of 
printing a MetaFile than that described earlier using GpiPlayMetaFile, it lacks 
the flexibility provided by the GpiPlayMetaFile options. Note that Piclchg also 
provides the capability of converting symbol sets to fonts. Symbol sets resemble 
fonts but represent an earlier character set architecture (used by PIF files and 
other products). 


/* recmeta.c */ 

BOOL RecordMetaFi1e (HAB hab, HPS hps, PSZ pszFilename ) 

{ 

/* Record a MetaFile and save it to disk. The input PS must not be associated */ 
/* with a DC. */ 

/* */ 

/* inputs: hab anchorblockhandle * / 

/* hps PS handle */ 

/* pszFilename file name for new MetaFile */ 

/* */ 


//define METAFILETEXT “Have a nice day!” 

//define METAFI LETEXTLEN ( LONG) ( si zeof (METAFI LETEXT)) 


HDC hdc 

; 


/* 

DC handle 

*/ 

HMF hmf = DEV_ERR0R ; 


/* 

MetaFile handle 

*/ 

BOOL fRet = FALSE 



/* 

BOOL return code 

*/ 

POINTL ptlPoint 



/* 

coordinate point 

*/ 

DEVOPENSTRUC dopData 



/* 

DEVOPENSTRUC structure 

*/ 

static MATRIXLF matlf = { 

0x20000 

0L, 

0L, 0L, 0x20000, 0L, 20L, 20L, 1L } 





/* 

set DevOpenDC params 

*/ 

dopData.pszLogAddress 

= NULL; 

/* 

-logical address 

*/ 

dopData.pszDriverName 

= “DISPLAY” 

/* 

-driver name 

*/ 

dopData.pdriv 

= NULL 


/* 

-DRIVDATA 

*/ 

dopData.pszDataType 

= NULL 


/* 

-data type 

*/ 

dopData.pszComment 

= NULL 


/* 

- comment 

*/ 

dopData.pszQueueProcName 

= NULL 


/* 

-queue proc name (default) 

*/ 

dopData.pszQueueProcParams 

= NULL 


/* 

-queue proc params 

* 

dopData.pszSpoolerParams 

= NULL 


/* 

-spooler params 

*/ 

dopData.pszNetworkPa rams 

= NULL 


/* 

-network params (not used) 

*/ 


Figure 11.1 RecordMetaFile Function. 
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DevOpenDCC hab 

, OD_METAFILE 


(PDEVOPENDATA)&dopData 
NULL 


/* open a MetaFile DC 
/* -anchor block handle 
/* -DC type 
/* -token 

/* -number of data elements 
/* -open DC data 
/* -compatible hdc (N/A) 


'* _ *******/ 
/* Load resources and modify PS environment here or immediately after */ 

/* GpiAssociate (or GpiCreatePS with GPIA_ASSOC option) i.e. logical */ 
/* color tables, logical fonts, bitmaps, default attributes, default view */ 
/* matrix and PS page units). Note that GpiSetPS may not be issued after */ 
/* GpiAssociate. */ 


if(hdc!=DEV_ERROR) /* load r 

fRet = GpiSetDefaultViewMatrix( hps /* enviro 

, 9L 

, &matlf 

, TRANSF0RM_REPLACE 

); 


/* load resources and modify PS */ 
/* environment as required */ 


if(fRet) 

fRet = GpiAssociate( hps 
, hdc 
); 


/* associate PS and DC 
/* -PS handle 
/* -DC handle 


ptl Point.x = 100L; 
ptl Point.y = 100L; 

if (fRet) /* dr 

fRet = (BOODGpiCharStringAt( hps 

, &ptlPoint 
, METAFILETEXTLEN 
, METAFILETEXT 
); 


/* draw to MetaFile 


if (fRet) 

fRet = GpiAssociate( hps 
, NULL 
); 


/* dissociate PS and DC 
/* -PS handle 
/* -DC handle (NULL) 


/* Destroy PS resources here. 
/* 


if (hdc!=DEV_ERR0R) 
hmf = DevCloseDC(hdc); 

if (hmf!=DEV_ERR0R && fRet) 
fRet = GpiSaveMetaFi1e( hmf 

, pszFilename 

); 

else 

fRet = FALSE; 


/* close the DC 

/* save MetaFile to disk 
/* -MetaFile handle 
/* -file name 


return(fRet); 


Figure 11,1 (continued) 
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/* crtmeta.c */ 

HMF CreateMetaFile(HAB hab, LONG IDataLength, PBYTE pbMetaFi1eData) 


it from application memory. */ 

*/ 

hab anchor block handle */ 

IDataLength length of MetaFile data (application buffer) */ 

pbMetaFi1eData pointer to MetaFile data (application buffer) */ 

HMF MetaFile handle or DEV_ERR0R */ 

*/ 


{ 

/* Create a MetaFile and initialize 
/* 

/* inputs: 

/* 

/* 

/* 

/* returns: 

/* 

HDC hdc 

BOOL fRet = FALSE 

DEVOPENSTRUC dopData 
HMF hmf = DEV_ERR0R 


/* DC handle */ 
/* BOOL return code */ 
/* DEVOPENSTRUC structure */ 
/* MetaFile handle */ 


dopData.pszLogAddress 
dopData.pszDriverName 
dopData.pdriv 
dopData.pszDataType 
dopData.pszComment 
dopData.pszQueueProcName 
dopData.pszQueueProcParams 
dopData.pszSpoolerParams 
dopData.pszNetworkParams 


NULL; 

“DISPLAY”; 

NULL; 

NULL; 

NULL; 

NULL; 

NULL; 

NULL; 

NULL; 


hdc = DevOpenDC( hab 

, 0D_METAFILE 

! 9L 

, (PDEVOPENDATA)&dopData 
, NULL 


/* set DevOpenDC data */ 
/* -logical address */ 
/* -driver name */ 
/* -DRIVDATA */ 
/* -data type */ 
/* -comment */ 
/* -queue proc name (default) */ 
/* -queue proc params */ 
/* -spooler params */ 
/* -network params (not used) */ 

/* open a MetaFile DC */ 
/* -anchor block handle */ 
/* -DC type */ 
/* -token */ 
/* -number of data elements */ 
/* -open DC data */ 
/* -compatible hdc (N/A) */ 


if (hdc!=DEV_ERR0R) 
hmf = DevCloseDC(hdc); 


/* close MetaFile DC */ 


if (hmf!=DEV_ERR0R) 

fRet = GpiSetMetaFi1eBits( 


/* set the MetaFile data 
hmf /* MetaFile handle 

0L /* MetaFile Offset 

IDataLength /* Length of data 

pbMetaFi1eData /* MetaFile data buffer 


*/ 

*/ 

*/ 

*/ 

*/ 


if (IfRet) /* delete if error */ 

{ 

GpiDeleteMetaFi1e(hmf); 
hmf = DEV_ERR0R; 


return(hmf); 

} 


Figure 11.2 CreateMetaFile Function. 
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/* playmeta.c */ 


BOOL PIayMetaFi1e(HPS hps, PSZ pszFileName) 

{ 

/* Play MetaFile to the PS with the combination of options that most */ 

/* accurately recreates the original the original MetaFile picture. */ 

/* */ 

/* inputs: hps PS handle */ 

/* pszFileName file name of MetaFile */ 

/* */ 


#define N0PTI0NS (LONG)(PMF_DEFAULTS+1) 
^define LDESC 256L 


BOOL fRet = FALSE 


/* 

BOOL return code 

*/ 

LONG ISegCount 


/* 

returned segment count 

*/ 

BYTE abDesc[LDESC] 


/* 

returned descriptive array 

*/ 

LONG alOpns[NOPTIONS] 


/* 

GpiPIayMetaFi 1 e options 

*/ 

HMF hmf = GPI ERROR 


/* 

MetaFile handle 

*/ 

SIZEL sizl 


/* 

PS size 

*/ 

ULONG ulOptions 


/* 

PS page units 

*/ 



/* 

query page units and size 

*/ 

ulOptions = GpiQueryPSC hps 

/* 

-PS handle 

*/ 

, & s i z 1 
); 

/* 

-PS size 

*/ 

if (ulOptions!=GPI_ERR0R) 


/* 

load the MetaFile 

*/ 

hmf = GpiLoadMetaFi1e( 

a b 

/* 

-anchor block handle 

*/ 

). 

)szFi 1 eName 

/* 

-file name 

*/ 



/* 

set play MetaFile options 

*/ 

alOpns[PMF SEGBASE] 

= OL; 

/* 

- reserved 

*/ 

alOpns[PMF LOADTYPE] 

= LT_ORIGINALVIEW; / * 

-transform option 

*/ 

alOpns[PMF RESOLVE] 

= OL; 

/* 

- reserved 

*/ 

alOpns[PMF LCIDS] 

= LC LOADDISC; 

/* 

-lcid option 

*/ 

alOpns[PMF RESET] 

= RES RESET; 

/* 

-reset option 

*/ 

alOpns[PMF_SUPPRESS] 

= SUP NOSUPPRESS; 

/* 

-suppress option 

*/ 

alOpns[PMF_COLORTABLES] 

= CTAB REPLACE; 

/* 

-color table option 

*/ 

alOpns[PMF_COLORREALIZABLE] = CREA_NOREALIZE; 

/* 

-color realize option 

*/ 

a 1Opns[PMF_DEFAULTS] 

= DDEF_LOADDISC; 

/* 

-default attribute option 

*/ 

if (hmf!=GPI_ERROR) 


/* 

pi ay the MetaFi1e 

*/ 

fRet = (BOOL)GpiPIayMetaFi1e( hps 

/* 

-PS handle 

*/ 


, hmf 

/* 

-MetaFile handle 

*/ 


, NOPTIONS 

/* 

-option count 

*/ 


, alOpns 

/* 

-Options 

*/ 


, &lSegCount 

/* 

-ret seg count (reserved) 

*/ 


, LDESC 

/* 

-size of descriptive array 

*/ 


, abDesc 
); 

/* 

-returned descriptive arra> 

'*/ 

if (hmf!=GPI_ERR0R) 


/* 

delete the MetaFile 

*/ 

fRet = GpiDeleteMetaFi1e(hmf) && fRet; 




if (fRet) 


/* 

restore PS page units etc. 

*/ 

fRet = GpiSetPS( hps 


/* 

PS handle 

*/ 

, & s i z 1 


/* 

PS size 

*/ 

, ulOptions 

/* 

PS page units etc. 

*/ 


); 


return (fRet); 

} 


Figure 11.3 Play MetaFile Function. 
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/* playmetm.c */ 

BOOL PIayMetaFi1e_Modify(HPS hps, PSZ pszFileName) 

{ 

/* Play the MetaFile first with the reset and suppress options to reset the */ 

/* PS to the page units etc. defined in the MetaFile. Next modify the PS */ 

/* resources as required then play the MetaFile a second time without */ 

/* specifying reset and suppress to display it. */ 

/* */ 

/* In the example given here, the PS color table is modified to change the */ 

/* background color to black and the neutral foreground color to white. The */ 

/* PS is then erased to black before drawing the MetaFile. This particular */ 

/* example will work for normal MetaFiles recorded with default background */ 

/* and foreground color table values as the MetaFile will not define the */ 

/* actual RGB values for these colors. MetaFiles that do define these RGB */ 

/* values will require the CTAB_N0M0DIFY option to be specified on the */ 

/* second and final GpiPIayMetaFi1e (i.e. to use the default color table). */ 
/* */ 

/* inputs: hps PS handle */ 

/* pszFileName file name of MetaFile */ 

/* */ 


//define NOPTIONS (LONG)(PMF_DEFAULTS+1) 
//define LDESC 256L 
//define NALTABLE 4L 


BOOL fRet = FALSE ; 

/* 

BOOL return code 

*/ 

LONG ISegCount ; 

/* 

returned segment count 

*/ 

BYTE abDesc[LDESC] ; 

/* 

returned descriptive array 

*/ 

LONG alOpns[NOPTIONS] ; 

/* 

GpiPIayMetaFi1e options 

*/ 

HMF hmf ; 

/* 

MetaFile handle 

*/ 

static LONG alTable[NALTABLE] = 

/* 

color table data 

*/ 

{ OL 

/* 

index 0 

*/ 

, 0x00000000L 

/* 

bl ack 

*/ 

, 7 L 

/* 

index 7 

*/ 

, OxOOFFFFFFL 
}; 

/* 

white 

*/ 


/* 

load the MetaFile 

*/ 

hmf = GpiLoadMetaFi1e( hab 

/* 

-anchor block handle 

*/ 

, pszFileName 

/* 

-file name 

*/ 

), 

/* 

set play MetaFile options: 

*/ 


/* 

for reset and suppress 

*/ 

alOpns[PMF SEGBASE] = 0L; 

/* 

- reserved 

*/ 

a 1Opns[PMF L0ADTYPE] = LT DEFAULT; 

/* 

-transform option 

*/ 

alOpns[PMF RESOLVE] = OL; 

/* 

- reserved 

*/ 

alOpns[PMF LCIDS] = LC_DEFAULT; 

/* 

-Icid option 

*/ 

a 1Opns[PMF RESET] = RES_RESET; 

/* 

-reset option 

*/ 

a 1Opns[PMF SUPPRESS] = SUP_SUPPRESS; 

/* 

-suppress option 

*/ 

alOpns[PMF COLORTABLES] = CTAB DEFAULT; 

/* 

-color table option 

*/ 

alOpns[PMF COLORREALIZABLE] = CREA DEFAULT; 

/* 

-col or realize option 

*/ 

alOpns[PMF_DEFAULTS] = DDEF_DEFAULT; 

/* 

-default attribute option 

*/ 

if (hmf!=GPI_ERR0R) 

/* 

play the MetaFile 

*/ 

fRet = (BOOL)GpiPIayMetaFi1e( hps 

/* 

-PS handle 

*/ 

, hmf 

/* 

-MetaFile handle 

*/ 

, NOPTIONS 

/* 

-option count 

*/ 

, alOpns 

/* 

-Options 

*/ 

, &!SegCount 

/* 

-ret seg count (reserved) 

*/ 

, LDESC 

/* 

-size of descriptive array 

*/ 

, abDesc 

/* 

-returned descriptive array*/ 


); 


Figure 11.4 PlayMetaFile_Modify Function. 
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if (fRet) 


/* change PS resources 

*/ 

fRet = GpiCreateLogCol orTabl e( hps 

/* -PS handle 

*/ 


, LCOL RESET 

/* -options 

*/ 


, LCOLF INDRGB 

/* -format 

*/ 


, OL 

/* -start index (N/A) 

*/ 


. NALTABLE 

/* -number of alTable elements 

*/ 


, alTable 
); 

/* -index/RGBcolor table array*/ 

if (fRet) 


/* erase the window 

*/ 

fRet = GpiErase(hps); 


/* background to black 

*/ 



/* set play MetaFile options: 

*/ 



/* no reset and normal play 

*/ 

alOpns[PMF SEGBASE] 

= OL; 

/* -reserved 

*/ 

alOpns[PMF LOADTYPE] 

- LT ORIGINALVIEW 

/* -transform option 

*/ 

alOpns[PMF_RESOLVE] 

= OL; 

/* -reserved 

*/ 

alOpns[PMF LCIDS] 

= LC_LOADDISC; 

/* -lcid option 

*/ 

alOpns[PMF RESET] 

= RES NORESET; 

/* -reset option 

*/ 

alOpns[PMF SUPPRESS] 

= SUP NOSUPPRESS; 

/* -suppress option 

*/ 

alOpns[PMF_COLORTABLES] 

= CTAB REPLACE; 

/* -color table option 

*/ 

alOpns[PMF COLORREALIZABLE] 

= CREA NOREALIZE; 

/* -color realize option 

*/ 

alOpns[PMF_DEFAULTS] 

= DDEF LOADDISC; 

/* -default attribute option 

*/ 

if (fRet) 


/* pi ay the MetaFi1e 

*/ 

fRet = (BOOL)GpiPIayMetaFi1e( hps 

/* -PS handle 

*/ 


, hmf 

/* -MetaFile handle 

*/ 


, (LONG)NOPTIONS/* -option count 

*/ 


, alOpns 

/* -Options 

*/ 


, &lSegCount 

/* -ret seg count (reserved) 

*/ 


, LDESC 

/* -size of descriptive array 

*/ 


, abDesc 

/* -returned descriptive array 

*/ 


); 

if (hmf!=GPI_ERROR) /* delete the MetaFile */ 

fRet = GpiDeleteMetaFi1e(hmf) && fRet; 

return (fRet); 

} 


Figure 11.4 (Continued) 
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/* printmet.c */ 

BOOL PrintMetaFi1e(HAB hab, HPS hps, HDC hdc, PSZ pszMetaFile) 

{ 

/* This function plays a MetaFile with the RES_RESET option to a PM_Q_STD, */ 

/* 0D_QUEUED printer DC. */ 

/* */ 

/* Play the MetaFile to the PS with RES_RESET and SUP_SUPPRESS options to */ 
/* reset the PS to match the MetaFile. Associate the PS and DC then play the */ 
/* MetaFile without the reset and suppress options. Dissociate the PS and DC */ 
/* and return. */ 

/* */ 

/* Note that the Reset option must be used before GpiAssociate to avoid a */ 
/* PMERR_INCOMPATIBLE_METAFILE error. It is assumed that the PS and DC are */ 
/* not associated on entry. */ 

/* */ 

/* inputs: hab anchor block handle */ 

/* hps PS handle */ 

/* hdc DC handle */ 

/* pszFileName file name of MetaFile */ 

/* */ 


//define PDOCNAME “Print Job” 

//define PDOCNAMELEN ( LONG) si zeof( PDOCNAME) 

//def i ne N0PTI0NS ( LONG) ( PMF_DEFAULTS+1) 
//define NDESC 256L 


BOOL fRet = FALSE 


/* 

BOOL return code 

*/ 

BOOL fRetA = FALSE 


/* 

BOOL return code 

*/ 

HMF hmf 


/* 

MetaFile handle 

*/ 

USHORT usJobld 


/* 

returned job id 

*/ 

LONG 1SegCount 


/* 

returned segment count 

*/ 

LONG abDesc[NDESC] 


/* 

returned descriptive array 

*/ 

LONG alOpns[N0PTI0NS] 


/* 

GpiPIayMetaFi1e options 

*/ 

LONG 1 Length 


/* 

1ength 

*/ 



/* 

load the MetaFile 

*/ 

hmf = GpiLoadMetaFi1e( hab 


/* 

-anchor block handle 

*/ 

, pszMetaFile 

. 

/* 

-MetaFile file name 

*/ 

j , 


/* 

set play MetaFile options 

*/ 



/* 

for reset and suppress 

*/ 

alOpnsEPMF SEGBASE] 

= OL; 

/* 

- reserved 

*/ 

alOpns[PMF LOADTYPE] 

= LT DEFAULT; 

/* 

-transform option 

*/ 

alOpns[PMF RESOLVE] 

= OL; 

/* 

- reserved 

*/ 

alOpns[PMF LCIDS] 

= LC DEFAULT; 

/* 

-lcid option 

*/ 

alOpns[PMF RESET] 

= RES RESET; 

/* 

-reset option 

*/ 

a 1Opns[PMF SUPPRESS] 

= SUP SUPPRESS; 

/* 

-suppress option 

*/ 

a 1Opns[PMF COLORTABLES] 

= CTAB DEFAULT; 

/* 

-color table option 

*/ 

alOpns[PMF_C0L0RREALI ZABLE] = CREA_DEFAULT; 

/* 

- col or realize option 

*/ 

alOpns[PMF_DEFAULTS] 

= DDEF_DEFAULT; 

/* 

-default attribute option 

*/ 



/* 

play the MetaFile with 

*/ 

if (hmf!=GPI_ERR0R) 


/* 

reset and suppress options 

*/ 

fRet = (BOOL)GpiPIayMetaFi1e( hps 

/* 

-PS handle 

*/ 


, hmf 

/* 

-MetaFile handle 

*/ 


, NOPTIONS 

/* 

-option count 

*/ 


, alOpns 

/* 

-Options 

*/ 


, &!SegCount 

/* 

-ret seg count (reserved) 

*/ 


, NDESC 

/* 

-size of descriptive array 

*/ 


, (PBYTE)abDesc 

/* 

-returned descriptive array*/ 


); 


Figure 11.5 PrintMetaFile Function. 
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if (fRet) 

fRet = fRetA = GpiAssociate(hps, hdc); 

1 Length = OL; 
if (fRet) 

fRet = DevEscapeC hdc 

, DEVESC_STARTDOC 
, PDOCNAMELEN 
, PDOCNAME 
, &1Length 
, NULL 

) == DEV_OK; 


/* 

associate PS 

and 

DC 

*/ 

/* 

issue 

start 

doc DevEscape 

*/ 

/* 

-DC he 

a nd 1 e 



*/ 

/* 

-escape code 



*/ 

/* 

-size 

of document 

name 

*/ 

/* 

-null 

termin 

ated 

doc name 

*/ 

/* 

-size 

of output data (OL) 

*/ 

/* 

-output data 

(not 

used 

*/ 


alOpns[PMF_SEGBASE] 
alOpns[PMF_LOADTYPE] 
alOpns[PMF_RESOLVE] 
alOpns[PMF_LCIDS] 
alOpns[PM F_ RESET] 
alOpns[PMF_SUPPRESS] 
alOpns[PMF_COLORTABLES] 
a 1Opns[PMF_COLORREALIZABLE] 
a 1Opns[PMF_DEFAULTS] 


/* set play MetaFile options: 
/* no reset and normal play 
= OL; /* -reserved 

= LT—0RIGINALVIEW;/* -transform option 
= OL; /* -reserved 

= LC—LOADDISC; /* -Icid option 

= RES_NORESET; /* -reset option 

= SUP_NOSUPPRESS; /* -suppress option 

= CTAB_REPLACE; /* -color table option 

= CREA_NOREALIZE; /* -color realize option 
= DDEF_LOADDISC; /* -default attribute option 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


if (fRet) 

fRet = (BOOL)GpiPIayMetaFi1e( 


/* 

hps /* 
hmf /* 
(LONG)NOPTIONS/* 
alOpns /* 
&!SegCount /* 
NDESC /* 
(PBYTE)abDesc /* 


pi ay the MetaFi1e */ 
-PS handle */ 
-MetaFile handle */ 
-option count */ 
-Options */ 
-ret seg count (reserved) */ 
-size of descriptive array */ 
-returned descriptive array*/ 


if (hmf!=GPI_ERROR) 

fRet = GpiDeleteMetaFi1e(hmf) && fRet; 

1 Length = 2L; 
if(fRet) 

fRet = DevEscape( hdc 

, DEVESC_ENDDOC 
, OL 
, NULL 
, &1Length 
, (PBYTE)&usJobId 
) == DEV_0K; 


if(fRetA) 

fRet = GpiAssociate(hps, NULL) && fRet; 
return(fRet); 


/* delete the MetaFile */ 


/* issue end doc DevEscape */ 
/* -DC handle */ 
/* -escape code */ 
/* -length of input data (OL) */ 
/* -input data (not used) */ 
/* -size of output data (2L) */ 
/* -output data (ret job id) */ 


/* dissociate PS and DC */ 


Figure 11.5 (continued) 
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/* scalemet.c */ 


BOOL SealeMetaFi1e(HPS hps, HMF hmf, PRECTL prclTarget) 

{ 

/* Play the specified MetaFile to the PS using the default view matrix to */ 

/* scale and translate the output to fit a specified rectangle in the PS */ 

/* page, while preserving the aspect ratio of the picture. Note that if the */ 

/* output device is a printer then it is the responsibility of the caller */ 

/* to issue the 'start document’ and 'end document’ escapes before and after */ 

/* invocation. */ 

/* */ 

/* inputs: hps PS handle */ 

/* hmf MetaFile handle */ 

/* prclTarget Target rectangle in page coordinates */ 

/* */ 


^define NOPTIONS (LONG)(PMF_DEFAULTS+1) 
^define LDESC 256L 


BOOL 

fRet 



/* BOOL return code 

*/ 

LONG 

1SegCount 



/* returned segment count 

*/ 

BYTE 

abDesc[LDESC] 



/* returned descriptive array 

*/ 

LONG 

alOpns[NOPTIONS] 



/* GpiPIayMetaFi1e options 

*/ 

POINTL 

ptlPosn 



/* coordinate point 

*/ 

RECTL 

rclBoundary 



/* boundary rectangle 

*/ 

MATRIXLF matlfXform 



/* transform Matrix 

*/ 

FIXED 

afxScale[2] 



/* x and y scale factors 

*/ 





/* set display control off 

*/ 

fRet = 

GpiSetDrawControl ( hp. 

5 


/* -PS handle 

*/ 


, DCTL 

DISPLAY 

/* -draw control 

*/ 


, DCTL_ 

.OFF 

/* -value 

*/ 


); 

if (fRet) 

fRet = GpiSetDrawControl( hps 

, DCTL_BOUNDARY 
, DCTL_0N 
); 


if (fRet) /* reset boundary data */ 
fRet = GpiResetBoundaryDataChps); /* -PS handle */ 

/* set play MetaFile options */ 
alOpns[PMF_SEGBASE] = OL; /* -reserved */ 
alOpns[PMF_LOADTYPE] = LT_N0M0DIFY; /* -transform option */ 
alOpns[PMF_RESOLVE] = OL; /* -reserved */ 
alOpns[PMF_LCIDS] = LC_LOADDISC; /* -lcid option */ 
alOpns[PMF_RESET] = RES_NORESET; /* -reset option */ 
alOpns[PMF_SUPPRESS] = SUP_NOSUPPRESS; /* -suppress option */ 
alOpns[PMF_COLORTABLES] = CTAB_REPLACE; /* -color table option */ 
alOpns[PMF_C0L0RREALI ZABLE] = CREA_NOREALIZE; /* -color realize option */ 
alOpns[PMF_DEFAULTS] = DDEF_LOADDISC; /* -default attribute option */ 


/* set bounds accumulation on */ 
/* -PS handle */ 
/* -draw control */ 
/* -value */ 


Figure 11.6 ScaleMetaFile Function. 
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/* 

if (fRet) 


/* 

fRet = 

(BOOL)GpiPIayMetaFi1e( hps 

/* 


, hmf 

/* 


, NOPTIONS 

/* 


, alOpns 

/* 


, &lSegCount 

/* 


, LDESC 

/* 


, abDesc 
); 

/* 

if (fRet) 


/* 

fRet = 

GpiQueryBoundaryData( hps 

/* 


, &rclBoundary 

/* 


); 


pi ay the MetaFi1e to */ 
accumulate boundary data */ 
-PS handle */ 
-MetaFile handle */ 
-option count */ 
-Options */ 


-ret seg count (reserved) */ 
-size of descriptive array */ 
-returned descriptive array*/ 


query the boundary data */ 
-PS handle */ 
-boundary rectangle */ 


/* Determine scale parameters to scale from boundary dimensions to target */ 

/* dimensions about bottom left of boundary. Ensure that both scale */ 

/* factors are equal and set to the smaller of the two possible values (to */ 

/* preserve the aspect ratio of the picture). */ 

afxScale[0] = (prclTarget->xRight - prclTarget->xLeft) * 0x10000 
/ (rclBoundary.xRight - rclBoundary.xLeft); 
afxScaleC1] = (prclTarget->yTop - prclTarget->yBottom) * 0x10000 
/ (rclBoundary.yTop - rclBoundary.yBottom); 


if (afxScale[0] < afxScale[l]) 
afxScale[l] = afxScale[0]; 
el se 

afxScale[0] = afxScale[l]; 
ptlPosn.x = rclBoundary.xLeft; 
ptlPosn.y = rclBoundary.yBottom; 

if (fRet) 

fRet = GpiScale( hps 

, &matlfXform 
, TRANSF0RM_REPLACE 
, afxScale 
, &ptlPosn 
); 


/* obtain scaling matrix */ 
/* -PS handle */ 
/* -transform matrix */ 
/* -options */ 
/* "X and y scale factors */ 
/* -center of scaling */ 


/* Add required translation to translate from boundary bottom left to taraet */ 
/* bottom left. *, 


ptlPosn.x = prclTarget->xLeft - 
ptlPosn.y = prclTarget->yBottom 
if (fRet) 

fRet = GpiTranslate( hps 

, &matlfXform 
, TRANSFORM_ADD 
, &ptlPosn 
); 


Boundary.yBottom; 

/* update matrix for translation 
/* -PS handle 
/* -transform matrix 
/* -options 
/* -translation 


rclBoundary.xLeft; 
- rcl 


*/ 

*/ 

*/ 

*/ 

*/ 


if (fRet) 

fRet = GpiSetDefaultViewMatrix( hps 

, 9 L 


); 


/* set default view matrix 
/* -PS handle 

/* -number of matrix element 
&matlfXform /* -transform matrix 
TRANSFORM_REPLACE /* -options 


*/ 

*/ 

*/ 

*/ 

*/ 


Figure 11.6 (continued) 
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if (fRet) 

/* 

set bounds accumulation off*/ 

fRet = GpiSetDrawControl( hps 

/* 

-PS handle 

*/ 

, DCTL BOUNDARY 

/* 

-draw control 

*/ 

, DCTL OFF 
); 

/* 

-value 

*/ 

if (fRet) 

/* 

set display control on 

*/ 

fRet = GpiSetDrawControl( hps 

/* 

-PS handle 

*/ 

, DCTL DISPLAY 

/* 

-draw control 

*/ 

, DCTL ON 
) ; 

/* 

-value 

*/ 

if (fRet) 

/* 

pi ay MetaFi1e 

*/ 

fRet = (BOOL)GpiPIayMetaFi1e( hps 

/* 

-PS handle 

*/ 

, hmf 

/* 

-MetaFile handle 

*/ 

, NOPTIONS 

/* 

-option count 

*/ 

, alOpns 

/* 

- Options 

*/ 

, &!SegCount 

/* 

-ret seg count (reserved) 

*/ 

, LDESC 

/* 

-size of descriptive array 

*/ 

, abDesc 

/* 

-returned descriptive array*/ 


); 


return (fRet); 

Figure 11.6 (continued) 


/* subpicme.c */ 


BOOL SubpictureMetaFi1e(HPS hps, HMF hmf, PRECTL prclTarget) 

{ 

/* Play the specified MetaFile to the PS as a subpicture using the viewing */ 

/* transform matrix to scale and translate the output to fit a specified */ 

/* rectangle in the PS page, regardless of the value of the default view */ 

/* matrix. The background of the subpicture will be cleared to white. */ 

/* */ 

/* The specified PS must be of type GPIT_NORMAL to allow use of */ 

/* GpiSetViewingTransformMatrix and GpiOpenSegment. */ 

/* */ 

/* It is assumed that the drawing mode is set to DM_DRAW (i.e. default value) */ 
/* on invocation. */ 

/* */ 

/* It is assumed that the MetaFile itself does not depend on any of its own */ 
/* internal viewing transform values for its correct appearance (as these */ 

/* are ignored in favour of the matrix provided for subpicturing). */ 

/* */ 

/* inputs: hps PS handle (type GPIT_NORMAL) */ 

/* hmf MetaFile handle */ 

/* prclTarget Target rectangle in page coordinates */ 

/* */ 


^define NOPTIONS (LONG)(PMF_DEFAULTS+1) 
^define LDESC 256L 


Figure 11.7 SubpictureMetaFile Function. 
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BOOL fRet 

LONG lSegCount 

BYTE abDescELDESC] 

LONG alOpns[NOPTIONS] 

POINTL ptlPosn 

RECTL rclBoundary 

MATRIXLF matlfXform 

RECTL rclTarget 

FIXED afxScale[2] 

static MATRIXLF matlfIdentity 


0x10000, 


fRet = GpiSetDrawControl( hps 

, DCTL_DISPLAY 
, DCTL_0FF 
); 


/* BOOL return code */ 

/* returned segment count */ 

/* returned descriptive array */ 
/* GpiPIayMetaFi1e options */ 

/* coordinate point */ 

/* boundary rectangle */ 

/* transform Matrix */ 

/* target rectangle */ 

/* x and y scale factors */ 

0, 0, 0, 0x10000, 0, OL, OL, 1L }; 
/* set display control off */ 

/* -PS handle */ 

/* -draw control */ 

/* -value */ 


if (fRet) 

fRet = GpiSetDrawControl ( 


hps 

DCTL_BOUNDARY 

DCTL_0N 


/* set bounds accumulation on */ 
/* -PS handle */ 
/* -draw control */ 
/* -value */ 


if (fRet) 

fRet = GpiResetBoundaryData(hps); 


/* reset boundary data */ 

/* -PS handle */ 


a 1Opns[PM F_S EGBAS E] 
a 1Opns[P M F_ LOADTYPE] 
alOpns[P M F_ RESOLVE] 
a 1Opns[PMF_LCIDS] 
a 1Opns[P M F_ RESET] 
a 1Opns[PMF_SUPPRESS] 
a 1Opns[PMF_C0L0RTAB LES] 
a 1Opns[PMF_C0L0RREALIZABLE] 
alOpns[PMF_DEFAULTS] 



/* set play MetaFile options 

*/ 

OL; 

/* -reserved 

*/ 

LT NOMODIFY; 

/* -transform option 

*/ 

OL; 

/* -reserved 

*/ 

LC LOADDISC; 

/* -lcid option 

*/ 

RES NORESET; 

/* -reset option 

*/ 

SUP NOSUPPRESS; 

/* -suppress option 

*/ 

CTAB REPLACE; 

/* -color table option 

*/ 

CREA NOREALIZE; 

/* -color realize option 

*/ 

DDEF LOADDISC; 

/* -default attribute option 

*/ 


/* play the MetaFile to */ 

if (fRet) /* accumulate boundary data */ 

fRet = (BOOL)GpiPIayMetaFi1e( hps /* -PS handle */ 

> hmf /* -MetaFile handle */ 

, NOPTIONS /* -option count */ 

, alOpns /* -Options */ 


&!SegCount /* -ret seg count (reserved) */ 
LDESC /* -size of descriptive array */ 
abDesc /* -returned descriptive array*/ 


if (fRet) /* query the boundary data */ 

fRet = GpiQueryBoundaryData( hps /* -PS handle */ 

, &rclBoundary /* -boundary rectangle */ 

); 

/* convert target rectangle coordinates from page to default page to allow */ 

/* the effect of default view matrix on the target */ 


Figure 11.7 (continued) 
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rclTarget.xLeft = prclTarget->xLeft; 


rclTarget.xRight = 

prclTarget->xRight; 

/* 

convert target rectangle 

*/ 

rclTarget.yBottom = 

prclTarget->yBottom; 

/* 

coordinates from page to 

*/ 

rclTarget.yTop 

prclTarget->yTop; 

/* 

default page 

*/ 

if (fRet) 


/* 


*/ 

fRet = GpiConvert( 

hps 

/* 

-PS handle 

*/ 


CVTC PAGE 

/* 

-source 

*/ 

, 

CVTC DEFAULTPAGE 

/* 

-target 

*/ 

9 

2L 

/* 

-count of coordinates 

*/ 

, 

(PP0INTL)(&rclTarget) 

/* 

-coordinate array 

*/ 


); 

/* Determine scale parameters to scale from boundary dimensions to target */ 
/* dimensions about bottom left of boundary. Ensure that both scale factors */ 
/* are equal and set to the smaller of the two possible values (to preserve */ 


/* the aspect ratio of the picture). */ 

if (rclBoundary.xRight > rclBoundary.xLeft) /* avoid divide by zero */ 

afxScale[0] = (rclTarget.xRight - rclTarget.xLeft) * 0x10000 
/ (rclBoundary.xRight - rclBoundary.xLeft); 

else 

afxScaleCO] = 0x10000; /* 1.0 */ 

if (rclBoundary.yTop > rclBoundary.yBottom) /* avoid divide by zero */ 

afxScaleCl] = (rclTarget.yTop - rclTarget.yBottom) * 0x10000 
/ (rclBoundary.yTop - rclBoundary.yBottom); 

else 

afxScale[1] = 0x10000; /* 1.0 */ 


if (afxScale[0] < afxScale[l]) 
afxScale[l] = afxScaleCO]; 
el se 

afxScaleCO] = afxScale[l]; 
ptlPosn.x = rclBoundary.xLeft; 
ptlPosn.y = rclBoundary.yBottom; 


if (fRet) 

/* obtain scaling matrix 

*/ 

fRet = GpiScale( hps 

/* -PS handle 

*/ 

, &matlfXform 

/* -transform matrix 

*/ 

, TRANSF0RM_REPLACE 

/* -options 

*/ 

, afxScale 

/* -x and y scale factors 

*/ 

, &pt1Posn 
); 

/* -center of sealing 

*/ 

Add required translation to translate from boundary bottom left to target 

*/ 

bottom left. 


*/ 

ptlPosn.x = rclTarget.xLeft - rclBoundary, 

, xLeft; 


ptlPosn.y = rclTarget.yBottom - rclBoundary.yBottom; 


if (fRet) 

/* update matrix for translation 

*/ 

fRet = GpiTranslate( hps 

/* -PS handle 

*/ 

, &matlfXform 

/* -transform matrix 

*/ 

, TRANSFORM_ADD 

/* -options 

*/ 

, &ptlPosn 

/* -translation 

*/ 


); 


Figure 11.7 (continued) 
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if (fRet) /* set viewing transform matrix */ 
fRet = GpiSetViewingTransformMatrix( hps /* -PS handle */ 

, 9L /* -number of matrix elements */ 
, &matlfXform /* -transform matrix */ 
, TRANSF0RM_REPLACE /* -options */ 
); 

if (fRet) /* set bounds accumulation off*/ 
fRet = GpiSetDrawControl( hps /* -PS handle */ 

, DCTL_BOUNDARY /* -draw control */ 
, DCTL_0FF /* -value */ 
); 

if (fRet) /* set display control on */ 
fRet = GpiSetDrawControl( hps /* -PS handle */ 

, DCTL_DISPLAY /* -draw control */ 
, DCTL_0N /* -value */ 
); 

if (fRet) /* reset model transform matrix */ 
fRet = GpiSetModelTransformMatrix( hps /* -PS handle */ 

, 9L /* -number of matrix elements */ 
, &matlfIdentity /* -transform matrix */ 
, TRANSF0RM_REPLACE /* -options */ 
); 


/* clear subpicture rectangle to white before playing the MetaFile to draw */ 
/* the subpicture. */ 



/* 

open segment zero to set 

*/ 

if (fRet) 

/* 

viewing transform attribute*/ 

fRet = GpiOpenSegment( hps 

/* 

-PS handle 

*/ 

, OL 
); 

/* 

-segment id (zero) 

*/ 

if (fRet) 

/* 

set color to white 

*/ 

fRet = GpiSetColor( hps 

/* 

-PS handle 

*/ 

, CLR WHITE 
); 

/* 

-col or 

*/ 

ptlPosn.x = rclBoundary.xLeft; 

ptlPosn.y = rclBoundary.yBottom; 

/* 

set current position to 

*/ 

if (fRet) 

/* 

boundary bottom left 

*/ 

fRet = GpiMove( hps 

/* 

-PS handle 

*/ 

, &ptlPosn 
); 

/* 

-coordinate point 

*/ 

ptlPosn.x = rclBoundary.xRight; 
ptlPosn.y = rclBoundary .yTop; 

if (fRet) 

/* 

clear boundary rectangle 

*/ 

fRet = (BOOL)GpiBox( hps 

/* 

-PS handle 

*/ 

, DR0_FILL 

/* 

- control 

*/ 

, &ptlPosn 

/* 

-corner coordinate point 

*/ 

, OL 

/* 

-rounding 

*/ 

, OL 

/* 

-rounding 

*/ 


Figure 11.7 (continued) 
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/* 


if (fRet) 

/* 

close segment 

*/ 

fRet = GpiCloseSegment(hps ) ; 

/* 

-PS handle 

*/ 

if (fRet) 

/* 

set color to default 

*/ 

fRet = GpiSetColor( hps 

/* 

-PS handle 

*/ 

, CLR DEFAULT 
) ; 

/* 

-col or 

*/ 

now play the MetaFile to draw the subpicture 


*/ 

alOpns[PMF LCIDS] = LC NOLOAD; 

/* 

-lcid option 

*/ 

alOpns[PMF DEFAULTS] = DDEF IGNORE; 

/* 

-default attribute option 

*/ 

if (fRet) 

/* 

play MetaFile 

*/ 

fRet = (BOOL)GpiPIayMetaFi1e( hps 

/* 

-PS handle 

*/ 

, hmf 

/* 

-MetaFile handle 

*/ 

, NOPTIONS 

/* 

-option count 

*/ 

, alOpns 

/* 

-Options 

*/ 

, &lSegCount 

/* 

-ret seg count (reserved) 

*/ 

, LDESC 

/* 

-size of descriptive array 

*/ 

, abDesc 

/* 

-returned descriptive array*/ 


); 


return (fRet); 

Figure 11.7 (continued) 
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Printing 


Throughout this chapter, the term printing is used to refer to both printing and 
plotting. Also, in the examples, the terminology used for queue and printer names 
is taken from IBM OS/2 Version 1.2 rather than 1.3. Queue names, for example, 
are called LPT1Q, LPT2Q, COM1Q , and so forth, and printer names PRINTER1, 
PRINTER2, PLOTTERl, and so forth. This scheme is followed in order to ensure 
that queue names are distinct from printer names. Such a naming scheme can be 
employed on Version 1.3, but by default, a queue and printer will both have the 
same name (e.g., LASER1). 

OS/2 provides a variety of different ways of printing enabling an end user or an 
application to print: 

• Gpi graphics and text. 

• Raw (device dependent) printer data. 

• Data in some other format unique to a particular print queue proces¬ 
sor or queue processor and driver. 

For many printer drivers, raw printer data is the same as raw ASCII text, 
although raw printer data may include additional escapes that are specific to a 
particular printer. The main exception is the PostScript driver (pscript.drv), which 
has its own unique format for raw data and does not currently support printing of 
raw ASCII text. 

Print operations can be either direct or queued (i.e., printed via the spooler). 

direct printing (dg types od jjsrect) 

With direct printing, data is output directly from an application (via the print 
drivers) to the printer, bypassing the print queue. This method is used by the 
system for printing queued print files when they are dequeued (see below). 
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Direct printing is not really intended for normal application use. In a multi-ap¬ 
plication system such as OS/2, different applications may be attempting to print 
concurrently. With direct (application) printing this could allow interference be¬ 
tween print jobs from different applications, or force an end user to wait for 
completion of one print job before being able to initiate another from the same 
application. 

If the OS/2 Spooler is disabled using the Print Manager then this will force all 
queued printing to be direct. 


QUEUED PRINTING (DC TYPES 0D_QUEUED) 


With queued printing, print data is intercepted by the Spooler, accumulated in a 
print file and enqueued on the print queue. Print files from all sources are 
dequeued from the print queue according to job priority, passed to the appropriate 
print queue processor, and printed by the system (using direct printing) on the 
appropriate printer. This is the normal mode of printing applications should use 
whenever possible. 

Early versions of some applications may recommend that the Spooler be dis¬ 
abled, effectively converting all queued printing to direct. This advice should be 
ignored unless problems are encountered. Most problems with the Spooler and 
drivers on early releases of OS/2 were corrected by Corrective Service Diskettes 
(CSDs) and subsequent releases. Any remaining problems are likely to be the fault 
of the application, in which case it may be necessary to obtain a corrected version 
of this. The Spooler should only be disabled as a last resort. 


TYPES OF PRINTING 

OS/2 provides many different ways of initiating a print operation, all of which use 
one of the following three types of printing. 

Base Control Program Printing 

Base Control Program printing includes any of the following operations: 

• DosOpen(LPTl) - Dos Write - DosClose (application request). 

• Dos Mode Int 21 and BIOS Int 17 (application request). 

• Print command (user request). 

• Copy file LPT1 (user request). 

• Print Screen Key (user request). 

• Redirection using >prn (user request). 

If the Spooler has not been disabled, all Base Control Program print jobs are 
queued. 
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Presentation Manager Printing 

Presentation Manager printing is the method used by most PM applications, 
including the File Manager and the (EE) Communication Manager. The PM API 
calls support both direct and queued printing and can be used with any of the 
following data types: 

“PM_Q_RAW” (raw device dependent format) 

As mentioned above, for most printers, the PM_Q_RAW format is 
the same as raw ASCII text with additional embedded escapes pro¬ 
viding the required device specific printer controls. Printing with 
this format can be accomplished using only Dev functions. 

“PM_Q_STD” (standard graphics format) 

This is standard graphics format supporting any GPI graphics 
and text output. 

The intention of PM_Q_STD, as opposed to PM_Q_RAW, format is 
to enable the format of print files to be device independent, theoreti¬ 
cally allowing them to be printed on any type of printer. This could 
eventually enable printer pooling with different printer types, but it 
is not currently possible to properly exploit this feature. In practice, 
PM_Q_STD print files may contain certain device dependencies. For 
example, they might reference device fonts or be dependent on de¬ 
vice resolution. OS/2 therefore tags each print job with the print 
driver and device name, forcing it to be printed on the correct device. 
Although printer pooling using different printer types is not cur¬ 
rently supported, printer pooling using printers of the same type is 
possible. 

A disadvantage of the PM_Q_STD format is that any fonts used 
by an application must be installed as public fonts on the local sys¬ 
tem for local printing, or on the print server node for network print¬ 
ing. Although PM_Q_RAW format does not have this restriction, 
PM_Q_STD is the recommended format. 

PM_Q_8TB format is based on, and closely resembles a MetaFile. 
A MetaFile can be enqueued as a PM_Q_STD print file using the 
Spooler Function Calls (see below). A PM_Q_STD print file can also 
be drawn using GpiPlayMetaFile. These two formats are not, how¬ 
ever, identical. A MetaFile will not necessarily contain all the 
printer control information that a PM_Q_STD print file contains 
and a PM_Q_STD print file may not correctly conform to the MetaF¬ 
ile interchange architecture. In particular, if logical fonts are cre¬ 
ated using IMatch (see chapter 4), the IMatch value will be recorded 
in a PM_Q_STD print file but not in a MetaFile. In addition, the 
DevEscape codes recorded in a PM_Q_STD print file will differ from 
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those recorded in a MetaFile (depending on the escape code value). 
Although currently these are the only real differences, it is possible 
that other differences will be added in the future. 

Other Strings 

Other strings can be used to specify special formats unique to the 
queue processor or both queue processor and a particular print 
driver. 


Spooler (Spg) Function Calls (Spooler API) 

The Spooler Function Calls (e.g., SplQmOpen) enable print files to be enqueued to 
the print queue and are primarily for use by the System and presentation drivers 
rather than by applications. The valid print file data types are those supported by 
the specified (or default) print queue processor and can be queried using the 
SplQpQueryDt function. For PMPRINT (the default OS/2 print queue processor) 
valid data types are: 

• “PM_Q_RAW” (raw device dependent format as described above) 

• “PM Q STD” (standard graphics format as described above). 

• Other Strings specifying queue processor specific formats. These 
may be unique to the queue processor or to a queue processor and a 
particular presentation driver. 

Although the Spooler Function Calls primarily exist for use by the System and 
presentation drivers, they also provide applications with a means of adding raw 
print data files or MetaFiles directly to the print queue, bypassing some of the 
application overheads associated with printing using Base Control Program and 
GPI calls. Note however that, as described above, the PM_Q_STD and MetaFile 
formats are not identical. Real PM_Q_STD print files, as opposed to MetaFiles, 
are created by the system in response to appropriate Dev and GPI functions and 
are discussed in the remainder of this chapter. 

The Spooler Function calls closely parallel the equivalent set of Dev functions 
and, with a good understanding of the latter, use of the Spooler Function calls is 
relatively straightforward. 


OS/2 PRINT SUBSYSTEM 

The OS/2 Print Subsystem is illustrated in Figure 12-1 and shows the Spooler 
Function Calls and the Base OS/2 File System (Base Control Program Printing) 
output being passed to the Spool Queue Manager for enqueueing on the print queue. 

Conceptually at least, presentation drivers consist of two parts. Presentation 
Driver (I) handles recording the data in the print file and Presentation Driver (II) 
handles the output to the printer. The output from PM print operations follows one 
of two paths depending on whether printing is direct or queued. Direct output goes 
directly to Presentation Driver (II) for immediate printing, whereas queued output 
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Printers 


Figure 12.1 OS/2 Print Subsystem. 


goes via the Presentation Driver (I) to the Spool Queue Manager for enqueueing 
on the print queue. 

As mentioned earlier, queued operation print files from all applications are 
removed from the print queue in turn, according to their priority, and printed by 
the system using direct printing. All print jobs, both direct and queued, eventually 
reach Presentation Driver (II) before being passed to the Base Print Device Driver 
for printing. This enables the presentation driver, as a minimum, to reset the 
driver between jobs, canceling any job related conditions remaining from the 
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previous job, and also enabling it to set any relevant job options (e.g., print quality 
number of characters per inch) required for the next job. 

A job in the print queue will only print if its ‘driver.device’ name matches that 
of a printer associated with the queue, the printer is connected to a valid port, and 
the form code specified for the job is either selectable or current (see below). If all 
these conditions are satisfied, then the job with the highest priority for a particular 
printer will be printed first on that printer. 

If raw printer data is being printed and the reset between jobs is not required 
(because, for example, the end user does not want the printer switch settings to be 
overridden) then the IBMNULL driver, provided for this purpose, should be used. 

In practice, Presentation Drivers (I) and (II) do not normally exist as separate 
components but they do provide a useful model for illustrating the operation of 
direct and queued printing. 


PRINTED INSTALLATION AND SET UP 

Although printer installation is a large and complex topic and is mainly outside 
the scope of this book, an understanding of the underlying model is important. 

Printer presentation drivers (some of which have dot-qualified device names, 
e.g., LASERJET.HP LaserJet II, PLOTTERS.IBM6180) are installed using the 
Control Panel or Print Manager. 

Printer set up involves establishing associations between: 

• A printer name (e.g., PRINTER1). 

• A single port or logical address (e.g., LPT1). 

• One or more presentation driver names (e.g., IBM4Q19, 
PSCRIPT.QMS™-PS810™) for use with this printer, with one of 
these selected as the default. 

and for the queue between: 

• A print queue name (e.g., LPT IQ). 

• A default print queue processor name (e.g., PMPRINT). 

• One or more printer names (e.g., PRINTER1, PRINTER2). 

• A default presentation driver name for this queue (this must be one 
that is associated with this printer name but need not be the same as 
the above default for this printer). 

Queue set up also establishes the first queue associated with a printer name as 
the default queue for this printer. 

A print queue and printer name can also be specified as application defaults. The 
application default printer need not be one that is associated with the default 
queue. 

Printer set-up examples are shown in Figures 12-2 and 12-3. The set up can be 
very simple as illustrated in Figure 12-2, with just a single queue associated with 
a single printer and presentation driver. Alternatively, it can be complex as 
illustrated in Figure 12-3, with multiple queues, multiple printers, and multiple 
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Figure 12.2 Printer Set Up Example 1. 


presentation drivers. This more complex set up provides a number of additional 
useful features: 

• The same presentation driver may be associated with more than one 
printer name, enabling the same type of printer (and driver) to be 
used on more than one port. 

® A printer name can have more than one associated presentation 
driver. This is useful, for example, if the port is switchable between 
different printer types, or for network printing, where the port is 
redirected (e.g., using “net use”) to a queue on a remote print server 
node, where the remote queue supports different printer types. 

• Different queues can be associated with the same printer name. This 
is called Printer Sharing and is useful if a choice of print job proper- 
ties is required without end user intervention. With such a configu¬ 
ration, an application is able to vary the job properties merely by 
switching queues. One queue, for example, could be set for landscape 
and another for portrait printing, with both queues sharing the same 
printer name, driver, and port. 

• A single queue can be associated with different printer names. This 
is called Printer Pooling and enables the same queue to be used for 
printing to different ports (the only presentation drivers available as 
defaults for this queue are those associated with all associated print¬ 
ers). This configuration is useful for a print server queue providing a 
pool of printers for use by the network. A pool of different printers 
will provide a choice of printer type whereas a pool of identical 
printers can be used to provide faster throughput of print jobs. 


NETWORK PRINTING 

For network printing from a requester to a remote print server, server queues and 
printers are not visible to a requester application except by using the DosPrint API 
(see below). It is not, therefore, possible for a requester application to open a DC 
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Figure 12.3 Printer Set Up Example 2. 


for a server queue or port. The server must share a printer queue (e.g., using net 
share Iptlq/print) and the requester must alias the server queue as one of its ports 
(e.g., using net use lpt4 \\server_name\lptlq). Provided both print requester and 
server are correctly set up, network printing on a remote print server node can be 
made transparent to an application initiating print requests from the requester. 
To achieve this, the server and requester must set up as follows: 
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®The presentation 'driver.device/ printer properties, and forms code 
specified for the requester (local) queue and printer must mirror those 
of the server queue and printer. This ensures that values used by a 
requester application are compatible with the server (the application 
continues to print using only the local dummy queue and printer port, 
unaware that its output is being redirected across the LAN). 

• The server queue network options (for IBM OS/2 Version 1.2) should 
include a ‘DRIVERS statement (e.g., DRIVER^ “PLOTTERS.IBM 
6180”). This is not essential for Presentation Manager printing as the 
jobs include this information, but Base Control Program print jobs 
require this in order to identify the presentation driver. A typical set 
of 1.2 server queue network options might be: 

DRIVER”“LASERJET.HP LaserJet IID” AFTER=09:00 
BEFORE=10:00 SEPARATORS:\SEP\IBMSERSEP” 

Here the AFTER and BEFORE keywords identify the times at which printing may 
occur and the SEPARATOR keyword identifies the name and location of the 
separator definition file. Note that separator files for most print drivers use ASCII 
text, but pscript drivers currently require separator page text to be defined using 
the PostScript language. Network options are not required by the requester queue. 
Note that on IBM OS/2 EE Version 1.3 these are no longer referred to as network 
options and are specified using individual dialog control windows rather than as 
a single string of network options. 


PRESENTATION MANAGER PRINTING FROM AN APPLICATION 

Presentation Manager printing from an application is probably best described in 
terms of the sequence of operations required. The steps are as follows: 

1. Establish a queue name for queued printing or port name for direct 
printing and the presentation driver and device names. 

2. Establish the DRIVDATA (driver data) structure for the driver and 
device. 

3. Open an OD QUEUED DC for queued printing or an OD_DIRECT DC 
for direct printing. 

4. Create a PS. 

5. Associate the PS and DC. 

6. Start the document by issuing a 'start document' DevEscape. 

7. Output the document or picture contents using GPI functions. 

8. End the document by issuing an 'end document' DevEscape. 

9. Dissociate the PS and DC. 

10. Destroy the PS. 

11. Close the DC. 

For raw data, no PS is required and the sequence is therefore: 
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1. Establish a queue name for queued printing or port name for direct 
printing and the presentation driver and device names. 

2. Establish the DRIVDATA (driver data) structure for the driver and 
device. 

3. Open an OD_QUEUED DC for queued printing or an OD_DIRECT DC 
for direct printing. 

4. Start the document by issuing a 'start document' DevEscape. 

5. Output the raw data using raw data' DevEscapes. 

6. End the document by issuing an 'end document' DevEscape. 

7. Close the DC. 

In addition, new frame' and ‘abort document' DevEscapes may be used (between 
the 'start document and 'end document' DevEscapes) to start a new page or to abort 
the print operation respectively. 

Establishing the Qu@ye s Port, Driver, Device, and DRIVDATA 

There are currently two main methods of establishing queue name, port name, 
driver name, device name, and the DRIVDATA structure, one based on printer 
selection and the other on queue selection. 

Printer Selection Method 

With this method, the application is unable to vary the job properties for a printer 
without end user intervention. It does, however, enable the application to optionally 
provide the user with a driver dialog on a 'per job' basis, allowing the user to specify 
printer properties as well as job properties and also update the INI file if required. 

This method requires the application first to select a printer name and then use 
this to determine: 

port name (required only for direct printing); 

presentation driver name for this printer; 

device name for this driver; and 

queue name (required only for queued printing). 

The printer name is established either by querying the default printer name or by 
querying a list of all available printer names and selecting one of these. 

1. The default printer name is determined using: 

PrfQueryProfileString (Application="PM_SPOOLER'', 
Key=“PRINTER”). 

This returns a null terminated printer name of the form: 


PRINTER!; 



PRINTING 


229 


This is illustrated by the function QueryDefaultPrinter in Figure 12-4 
(which removes the V replacing it by null). The list of all available 
printer names is determined using: 

PrfQueryProfileString (Application=“PM_SPOOLER_PRINTER”, 
Key=NULL). 

This returns a list of printer names of the form: 

PRINTERl PRINTER2 PRINTERS PLGTTRR1 

Each printer name in the list is terminated by a null with the final 
name terminated by two nulls. This is illustrated by the function 
QueryPrinterNames in Figure 12-5. 

2. Having obtained a printer name, this is used to determine the port, 
driver, device and queue names. These are determined using: 

PrfQueryProfileString (Application=“PM_SPOOLER_PRINTER”, 
Key=Printer name). 

This returns a null terminated string containing the port name, one or 
more driver names (with or without dot qualified device names), and 
one or more queue names. The names of the default driver and queue 
for the printer are those returned first. The returned string will be in 
one of the the following forms: 

LPT1;IBM4019;LPT1Q;; 

or 

C OM1; PLOTTERS. IBM6180; C OM IQ;; 
or 

LPT1;LASERJET.HP Laserjet Plus, PSCRIPT.QMS-PS810, 
IBM4019;LPT1Q,LPT12Q;; 

The final semicolon is intended to delimit a parameter string that is 
currently unused. This is illustrated by the function QueryPrinterlnfo 
in Figure 12-6, which separates the above string into a number of 
individual null terminated strings. 

3. The driver and device name are used with the printer name to obtain 
the DRIVDATA structure using DevPostDeviceModes. DevPostDevice 
Modes includes an options parameter allowing the application to 
specify one of the following: 

DPDM_POSTJOBPROP provides the end user with a dialog 
controlling job properties. This can also be used with a NULL 
Printer Name to allow the user to modify an existing 
DRIVDATA structure via the Job Properties dialog as described 
below for the Queue Selection Method. 
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DPDM_CHANGEPROP provides the end user with a dialog 
controlling both job and printer properties and the INI file is 
updated to reflect any changes. 

DPDM_QUERYJOBPROP provides no dialog to the end user; 
the job and printer properties used are the defaults from the INI 
file. 

DevPostDeviceModes should actually be issued twice, once with a 
NULL DRIVDATA pointer to determine the amount of memory re- 
quired and a second time, having allocated the memory, to obtain the 
DRIVDATA structure. This is illustrated by the function 
PostDeviceModes in Figure 12-7. 

Queue Selection Method 

This method obtains a DRIVDATA structure based on the print job properties 
associated with a specific print queue. This enables an application to vary job 
properties (such as portrait/la^dscape) for a printer on a per job’ basis without 
user intervention. This is accomplished by the application selecting the queue with 
the required job properties from one of a number of queues associated with the 
same printer. 

With this approach, the application does not obtain (or require) the port and 
printer name. Unless the the spooler is disabled, it cannot be used for direct 
printing. Also, without performing additional queries, an application has no 
absolute guarantee that the selected queue has an associated port and will print 
successfully (port selection is controlled by Print Manager set up). 

This method requires the application to first select a queue name and use this 
to determine the name of the default presentation driver for the queue. The queue 
name is established either by querying the default queue name or by querying a 
list of all available queue names and selecting one. 

1. The default queue is determined using: 

PrfQueryProfileString (Application"“PM_SPOOLER”, 

Key -"QUEUE”). 

This returns a null terminated queue name of the form: 

LPT IQ; 

This is illustrated by the function QueryDefaultQueue in Figure 12-8 
(which removes the replacing it by null). The list of all available 
queue names can be determined using: 

PrfQueryProfileString (Application = “PM_3POOLER_QUEUE”, 

Key - NULL). 

This returns a list of queue names of the form: 

LPT1Q LPT2Q LPT23Q COM1Q 
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Each name in the list is terminated by a null with the final name 
terminated by two nulls. This is illustrated by the function 
QueryQueueNames in Figure 12-9. 

2. Having obtained a queue name, this is used to determine the default 
presentation driver name for the queue and, where applicable, the 
device name. The default driver name and device name for the queue 
are determined using: 

PrfQueryProfileString (Application=“PM_SPOOLER_QUEUE_DD”, 
Key™queue name). 

Depending on the driver concerned, this returns either a null termi¬ 
nated driver name or driver.device name of the form: 

IBM4019; 

or 

PSCRIPT. QMS -PS810; 

This is illustrated by the function QueryQueueDriver in Figure 12-10 
(which removes the V and 7 replacing them by null). 

3. The driver name is used with the queue name to obtain the 
DRIVDATA structure using: 

PrfQuery Profile String (Application “PM_SPOOLER_QUEXJE_ 
DDBATA”, Key=queue name). 

This is illustrated by the function QueryQDriverData in Figure 12-11. 

4. This next step is optional. The end user can now be provided with a Job 
Properties dialog enabling the queue job properties to be modified. This 
is accomplished by passing the DRIVDATA structure obtained above as 
a parameter to DevPostDeviceModes with the DPDM_POSTJOBPROP 
option. This will return the DRIVDATA structure modified by the end 
user selections. This method may not be supported by all drivers, some 
of which may return an error. If an error is returned, the unmodified 
DRIVDATA structure can be used and the error ignored. This is 
illustrated by the function PostJobProperties in Figure 12-12. 

In addition to the printer and queue selection methods described above, there are 
two additional methods of defining the DRIVDATA structure described in Appen- 
dix 1, neither of which are recommended. These both cause all job and printer 
properties to be defaulted. 

Opening the 00 and Printing 

Having obtained the port or queue name and DRIVDATA structure using one of 
the above methods, it is now possible to open a DC and complete the print 
operation (using these as parameters to DevOpenDC). The functions 
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PrintDefPrinter and PrintDefQueue in Figures 12-13 and 12-14 illustrate the 
Queue Selection and Printer Selection methods for PM printing. The function 
PrintRawData in Figure 12-15 illustrates printing raw data using the Printer 
Selection method although the Queue Selection method would be equally valid. 

By capturing the display screen in a bitmap and inserting appropriate GpiBitBlt 
calls in either of the above (Printer or Queue Selection) methods, a print screen 
operation can be performed. 

By opening a file and drawing the ASCII text (as GPI character strings) in either 
of the above PM printing functions, an ASCII file can be printed as GPI text to any 
printer (e.g., see PrintTextBuffer in Figure 1-5.). 

By opening a file and outputting the ASCII text in the PrintRawData function, 
an ASCII file can be printed as raw text to most printers (but not pscript). 


FORM SELECTION 

An application wishing to use the Current Form for a printer need not be 
concerned with form selection. The Current Form will be selected automatically 
using the DRIVDATA structure obtained by one of the methods described above. 
Certain printers, such as those with multiple paper trays, allow the Form to be 
switched on a per job’ basis without intervention at the printer. This type of form 
selection can be accomplished in one of two ways: 

1. Using DevPostDeviceModes as described above, with options of 
DPDM_CHANGEPROP or DPDMJPOSTJOBPROP, the operator can 
select the required form for each job via the Job Properties dialog. 

2. The application can query a list of all available forms using 
DevQueryHardcopyCaps. This is another function that is actually 
issued twice, once to determine the number of forms and, having 
allocated the required memory, a second time to obtain the forms 
information. The forms are returned as an array of HCINFO struc¬ 
tures each containing form name, dimensions, and attributes. The 
attributes for each returned form specify HCAPS_CURRENT (form is 
current), HCAPS_SELECTABLE (form is selectable) or neither of 
these. The application may choose any form name with the 
HCAPS_SELECTABLE or HCAPS_CURRENT flag set and specify 
this in the DEVOPENSTRUC pszSpoolerParams of DevOpenDC (see 
Appendix 1). A job with a form name that is neither current nor 
selectable will stick in the print queue and not print. 


PRINT QUEUE PROCESSOR (QUEUE DRIVER) SELECTION 

The print queue processor (or queue driver) is responsible for interpreting the 
queue processor parameters and outputting a dequeued print file to the printer. 
A queue processor name is not required for direct printing and applications 
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using queued printing, if they have no special requirements, should default this 
parameter (by specifying NULL for the DevOpenDC DEVOPENSTRUC 
pszQueueProcName field). The following description of queue processor selection 
applies only to those applications with special queue processor requirements. 

Although a default print queue processor (PMPRINT) is provided and installed 
with OS/2, certain applications with special needs may require an alternative. For 
example, an application sending output to a plotter may wish to use the PMPLOT 
queue processor to perform hidden line removal or reverse clipping. Additional 
queue processors can be installed using the Control Panel (Add Queue Driver 
menu option) or the DosLoadModule and SplQpInstall functions. 

It is important when installing and deleting queue processors to ensure that the 
default queue processor is always one that is suitable for normal printing. This 
enables applications to use this default for general printing without the need to issue 
a query, specify a name, or be aware of different queue processor characteristics. 

When necessary, an application can query the installed queue processors using: 

PrfQueryProfileString (Application < TM_SPOOLER_QP”, 
Key=NULL) 

This returns a list of queue processor names of the form: 

PMPRINT PMPLOT MYQPROC 

Each name is terminated by a null with the final name in the list terminated by 
two nulls. This is illustrated by the function QueryQueueProcessors in Figure 
12-16. 


PIWJLSTO PRINTING RESTRICTIONS 

As explained earlier, PM_Q_STD print files are based on, and closely resemble 
MetaFiles, and like MetaFiles, certain restrictions apply when they are being 
recorded. Unlike MetaFiles, Print files need not conform to the interchange 
architecture but some restrictions are necessary in order to preserve picture 
integrity. 

The following rules and guidelines apply to OD_QUEUED/PM_Q_STD printing: 

1. All non-device fonts used in the picture must be installed as public 
fonts on the local system for local printing or on the print server for 
network printing. 

2. IMatch (match number) should not be used for logical font creation if 
printing is to take place on a different network node from the initiating 
application or if it is to be deferred until after a re-IPL. Match values 
are only valid in the local system for the duration of the current IPL 
session. 

3. If logical font creation without Match is used, scale to fit 5 options on 
DevOpenDC queue processor parameters should be avoided (i.e., spec¬ 
ify XFM=0). 
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4. If GpiBitBlt (as opposed to GpiWCBitBlt) is used, scale to fit' options 
on DevOpenDC queue processor parameters should be avoided (i.e., 
specify XFM=0). It the output is scaled to fit then the BitBlt output 
may be incorrectly positioned relative to the remainder of the picture. 

5. Bitmaps should not be modified after their first use. 

6. GpiDeleteBitmap should not be used until picture construction is 
complete. 

7. GpiDeleteSetld should not be used until picture construction is com¬ 
plete. 

8. GpiSetPS (or GpiPlayMetaFile with the RES_RESET option) must not 
be used after association with an OD_QUEUED/PM_Q_STD DC. This 
will return an error. 

9. GpiSetPage Viewport will be ignored. 

10. Large PM_Q_STD print jobs with many pages in the same job should 
be avoided if possible. Currently, these create a large temporary file in 
memory during print file recording. This can significantly degrade 
performance and, in some cases, produce an hut of memory' condition. 


PftlNTEH FONTS 

The Presentation Manager provides certain multi-purpose font files (courier.fon, 
times.fon, etc.) containing raster fonts with various point sizes and different device 
resolutions. Certain drivers are unable to display raster fonts at all, including 
those from these multi-purpose font files. This applies to the plotter and pscript 
drivers. 

In addition to the PM multi-purpose fonts and "built in' printer device fonts, 
certain printers offer a range of additional installable device fonts. These can 
include both soft fonts (i.e., fonts installed from diskette) and card or cartridge 
fonts. In either case, font definition (which defines the actual font cartridges 
installed) and soft font installation is performed using the Print Manager driver 
dialogs. As well as the files and cartridges that provide the actual font glyph 
definitions for the printer, additional files are required for both soft and card/car¬ 
tridge fonts to provide the corresponding font metric information. The font metric 
information is that which is returned to an application by GpiQueryFonts and 
GpiQueryFontMetrics to identify the metrics (or attributes) of these fonts to an 
application. 

Each print driver defines its own method of providing and installing soft and 
card/cartridge font files. 

The LASERJET driver uses .FNT files for the font metrics. Initially, on version 
1.2, these were supplied in packed form as .PCM files and later as individual .FNT 
files. New card or cartridge fonts purchased separately should be supplied with a 
.TFM file that can be unpacked to generate the .FNT files for these fonts. 

The IBM4019 uses .FMF and .CDF files that are distributed as a single .PMF 
file. The PMF files are unpacked into multiple FMF and CDF files by invoking the 
Install Initial Metrics—Font Cards dialog. 



PRINTING 


235 


Some printers may also offer additional matching display fonts to provide 
consistency between display and printer text appearance (this is sometimes 
referred to as What-You-See-Is-What-You-Get or WYSIWYG). 

As each raster font must be selected to match the resolution of the output device 
and matching raster fonts do not exist for every device, WYSIWYG using raster 
fonts is often difficult to achieve. This is not a problem with outline fonts that can 
be used on any device. The Adobe Type Manager provided with IBM OS/2 Version 
1.3 should make WYSIWYG possible using high quality outline font characters on 
any output device. 


BITMAP AND METAFILE PRINTING 

When using Bitmaps and MetaFiles with printers, certain restrictions apply. Also, 
bitmap inversion can occur under some conditions. For a discussion of bitmap and 
MetaFile printing, see chapters 5 and 11. 


OOSPRINT SPOOLER APS 

The DosPrint Spooler API is included in IBM OS/2 Version 1.3 and provides three 
groups of new functions: 

Print Destination Functions (e.g., DosPrintDestAdd) 

These begin with the prefix DosPrintDest and enable named print¬ 
ers to be queried, updated, created, deleted, and modified from an 
application program as well as by Print Manager set up. 

Queue Destination Functions (e.g., DosPrintQAdd) 

These begin with the prefix DosPrintQ and enable named printer 
queues to be queried, updated, created, deleted, and modified 
from an application program as well as by Print Manager set up. 

Print Job Functions (e.g., DosPrintJobDei) 

These begin with the prefix DosPrintJob and enable named print 
jobs to be queried, updated, paused, restarted, and deleted from 
an application program as well as by Print Manager set up. 

These functions are very powerful as, with a suitable privilege level, all opera¬ 
tions can be performed on a remote server node as well as on the local system. 
These functions all include a level number that determines the amount of data 
returned. 

There is some overlap between these and the PrfQueryProfileString functions 
described earlier and some of the string parsing complexities associated with the 
latter are eliminated. DosPrintDestEnum, for example, can be used to query (or 
enumerate) the available printer names, their logical address, and the drivers 
selected for each printer. DosPrintQEnum can be used to query (or enumerate) the 
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available queue names, the names of the printers connected to each queue, and 
the default driver (and its DRIVDATA structure) for each queue. Unlike 
PrfQuery Profile String, however, these functions cannot be used to obtain the 
application default queue and printer names. 


/* qdefprtr.c */ 

PSZ QueryDefaultPrinter(VOID) 


/* Return the default printer name. */ 
/* */ 
/* returns: PSZ Default printer name or NULL (error or not found). */ 
/* This function null terminates the string removing the */ 
/* */ 
/* It is the responsibi1ity of the caller to free the memory associated with */ 
/* the returned default printer name. */ 
/* e.g. pszString = QueryDefaultPrinter(); */ 
/* . */ 
/* free(pszString); */ 


PCHAR 

pch ; 

/* CHAR pointer 

*/ 

ULONG 

ulLength ; 

/* profile string size 

*/ 

BOOL 

fRet ; 

/* BOOL return code 

*/ 

LONG 

1 RetLen = 0L 

/* returned length 

*/ 

PSZ 

pszPrfStr = NULL ; 

/* profile string 

*/ 

PSZ 

pszPrtName = NULL ; 

/* default printer name 

*/ 



/* query name string size 

*/ 

fRet = 

PrfQueryProfi 1 eSi ze( HINI PROFILE 

/* -INI file handle 

*/ 


, “PM SPOOLER” 

/* -application name 

*/ 


, “PRINTER” 

/* -key name 

*/ 


, &ulLength 

/* -returned data length 

*/ 


); 


if (fRet && ulLength!=0) 

pszPrfStr = mal1oc((SHORT)ulLength); /* allocate memory for string */ 


if (pszPrfStr!=NULL) /* query default printer name */ 


IRetLen = PrfQueryProfi1eString( HINI_PR0FILE /* -INI file handle */ 

, “PM_SP00LER” /* -application name */ 
, “PRINTER” /* -key name */ 
, /* -default string */ 
, pszPrfStr /* -returned string */ 
, ulLength /* -max string length */ 


if (1 RetLen!=0) 

{ 

pch = strchr(pszPrfStr , ’ ; ' ); 
if (pchI=NULL && pch!=pszPrfStr) 
{ 

pszPrtName = pszPrfStr; 

*pch = ’\0 ’ ; 


if (pszPrtName==NULL) 
free(pszPrfStr); 


/* if string returned */ 

/* findstringend */ 

/* if name exists */ 

/* setname pointer */ 


/* null terminate string */ 


/* if error 

*/ 

/* free memory 

*/ 


return(pszPrtName); 

} 


Figure 12.4 QueiyDefaultPrinter Function. 
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/* 



qprtnams.c 

*/ 

PSZ QueryPrinterNames(VOID) 

r 




1 

/* Return the printer names. 



*/ 

/* 




*/ 

/* returns: PSZ Printer names or NULL (error 

or none found). 

*/ 

/* 

Note that each name is null terminated 

with the final name 

*/ 

/* 

terminated by two nulls. 



*/ 

/* 




*/ 

/* It is 

the responsibi1ity of the caller to 

free 

the memory associated with 

*/ 

/* the returned printer names. 



*/ 

/* e.g. 

pszString = QueryPrinterNames(); 



*/ 

/* 




*/ 

/* 

free(pszString); 



*/ 

ULONG 

ulLength ; 

/* 

profile string size 

*/ 

BOOL 

fRet ; 

/* 

BOOL return code 

*/ 

ULONG 

ulRetLen = OL ; 

/* 

returned length 

*/ 

PSZ 

pszPrfStr = NULL ; 

/* 

profile string 

*/ 

PSZ 

pszPrtNames = NULL ; 

/* 

printer names 

*/ 



/* 

query name string size 

*/ 

fRet = 

PrfQueryProfi1eSize( HINI_PR0FILE 

/* 

-INI file handle 

*/ 


, “PM_SP00LER_PRINTER” 

/* -application name 

*/ 


, NULL 

/* 

-key name 

*/ 


, &ulLength 

/* 

-returned data length 

*/ 


); 


if (fRet && ulLength!=0) 


pszPrfStr = mal1oc((SHORT)ulLength); 

/* 

allocate memory for string 

*/ 

if (pszPrfStr!=NULL) 


/* 

query printer names 

*/ 

ulRetLen = PrfQueryProf11eString( 

HINI PROFILE 

/* -INI file handle 

*/ 

, 

“PM_SPOOLER. 

PRINTER” /* -appl. name 

*/ 

, 

NULL 

/* 

-key name 

*/ 

, 

“ 99 

/* 

-default string 

*/ 

, 

pszPrfStr 

/* 

-returned string 

*/ 

); 

ulLength 

/* 

-max string length 

*/ 

if (ulRetLen!=0 && *pszPrfStr!='\0’) 


/* 

if first name exists 

*/ 

pszPrtNames = pszPrfStr; 


/* 

set printer names pointer 

■*/ 

if (pszPrtNames==NULL) 


/* 

if error 

*/ 

free(pszPrfStr); 


/* 

free memory 

*/ 


return(pszPrtNames); 

} 


Figure 12.5 QueryPrinterNames Function. 





238 


OS/2 PRESENTATION MANAGER CPI 


/* 

PSZ QueryPrinterlnfo( 


PSZ pszPrtName 
PSZ FAR* pszDefQ 
PSZ FAR* pszDefDrv 
PSZ FAR* pszDefDev 
PSZ FAR* pszAddlQs 
PSZ FAR* pszAdDrvDvs 


qprtinfo.c */ 


{ 


/* Query 

the printer port, default queue, default driver and device name and 

*/ 

/* additional queue and 

driver.device names 


*/ 

/* 





*/ 

/* inputs 

: pszPrtName 

Printer 

name (e.g. 

PRINTER1). 

*/ 

/* 





*/ 

/* outputs: *pszDefQ 

Default 

queue name 

(e.g. LPT1Q). 

*/ 

/* 

*pszDefDrv 

Default 

printer driver (e.g. LASERJET) or NULL. 

*/ 

/* 

*pszDefDev 

Default 

device name (e.g. HP LaserJet Plus) or NULL. 

*/ 

/* 

*pszAddlQs 

Additional queues 

(e.g. LPT2Q,LPT3Q) or NULL. 

*/ 

/* 

*pszAdDrvDvs 

Additional driver. 

device names or NULL. 

*/ 

/* 





*/ 

/* returns: PSZ port name (e.g. LPT1) or NULL (for error) 

*/ 

/* 





*/ 

/* It is 

the responsibility of the caller to free the memory associated with 

*/ 

/* the returned port name. 



*/ 

/* e.g. 

/ * 

pszString = QueryPrinterlnfo(..); 


*/ 

*/ 

/ 

/* 

free(pszString); 



*/ 

PCHAR 

pch 



/* CHAR pointer 

*/ 

ULONG 

ulLength 



/* profile string size 

*/ 

BOOL 

fRet 



/* BOOL return code 

*/ 

PSZ 

pszStart 



/* string start 

*/ 

LONG 

1RetLen 

= OL 


/* returned length 

*/ 

PSZ 

pszPrfStr 

= NULL 


/* profile string 

*/ 

PSZ 

pszPort 

= NULL 


/* port name 

*/ 

PSZ 

pszDefDrvLcl 

= NULL 


/* default driver name 

*/ 

PSZ 

pszDefQLcl 

= NULL 


/* default queue name 

*/ 

PSZ 

pszAddlQsLcl 

= NULL 


/* additional queue names 

*/ 

PSZ 

pszAdDrvDvsLcl 

- NULL 


/* additional driver.devices 

*/ 

PSZ 

pszDefDevLcl 

= NULL 


/* default device name 

*/ 





/* query string size 

*/ 

fRet = 

PrfQueryProfi1eSize( HINI_PROFILE 

/* -INI file handle 

*/ 



, “PM_SP00LER_PRINTER” /* -application name 

*/ 



, pszPrtName 

/* -key name 

*/ 



, &ulLength 

/* -returned data length 

*/ 


); 

if (fRet && ulLength!=0) 

pszPrfStr = mal1oc((SHORT)ulLength); /* allocate memory for string */ 


/* query printer info */ 
IRetLen = PrfQueryProfi1eString( HINI_PR0FILE /* -INI file handle */ 

, “PM_SP00LER_PRINTER” /* -application name */ 
, pszPrtName /* -key name */ 
, /* -default string */ 
, pszPrfStr /* -returned string */ 
, ulLength /* -max string length */ 
); 


Figure 12.6 QueryPrinterlnfo Function. 
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f (1 RetLen!=0) 


/* if string returned */ 




/* */ 

/* Now break the string into three null terminated strings: */ 

/* port name */ 

/* driver.device_names (beginning with default driver) */ 

/* queue_names (beginning with default queue) */ 

/* (ignore the network parameters) */ 

/* */ 




pszStart = pszPrfStr; 
pch = strchr(pszStart 
if (pch==NULL || pch==pszStart) 
{ 

free(pszPrfStr); 
return(NULL); 

} 

pszPort = pszStart; 

*pch = *\0 *; 

pszStart = ++pch; 
pch = strchr(pszStart,*;’); 
if (pch==NULL || pch==pszStart) 
{ 

free(pszPrfStr); 
return(NULL); 

} 

*pch = ’\0' ; 

pszDefDrvLcl = pszStart; 

pszStart = ++pch; 

pch = strchr(pszStart, ’ ; *); 

if (pch==NULL) 

{ 

free(pszPrfStr); 
return(NULL); 

} 

*pch = '\0’; 

if (pch!=pszStart) 

pszDefQLcl = pszStart; 


/* initialize pointer */ 

/* find port name end */ 

/* if no name exists */ 

/* free the memory */ 

/* return NULL */ 

/* null terminate string */ 

/* initialize pointer */ 

/* find def driver name end */ 
/* if no name exists */ 

/* free the memory */ 

/* return NULL */ 

/* null terminate string */ 

/* set def driver name */ 

/* initialize pointer */ 

/* find def queue name end */ 
/* if error */ 

/* free the memory */ 

/* return NULL */ 

/* null terminate string */ 

/* if name exists */ 

/* set queue name */ 




/* */ 

/* now break the queue_name string into two null terminated strings: */ 

/* default queue_name */ 

/* additional queue_names */ 

/* */ 




pszStart = pszDefQLcl; 

/* 

initialize pointer 

*/ 

pch = strchr(pszStart, ’, *); 

/* 

find ’, ’separator 

*/ 

if (pch!=NULL) 

/* 

if separator exists 

*/ 

*pch = f \0’; 

/* 

null terminate string 

*/ 

pszAddlQsLcl = ++pch; 

/* 

set addl queue names 

*/ 


} 


Figure 12,6 (continued) 
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j **************************************************************************/ 


/* */ 

/* now break the default driver.device_name string into two null */ 

/* terminated strings: */ 

/* default driver.device_name */ 

/* additional driver.device_names */ 

/* */ 


/**************************************************************************/ 


pszStart = pszDefDrvLcl; 

/* 

initialize pointer 

*/ 

pch = strchr(pszStart, ’ , ’); 

/* 

find ’ , ’separator 

*/ 

if (pch!=NULL) 

r 

/* 

if separator exists 

*/ 

1 

*pch = ’\0* ; 

/* 

null terminate string 

*/ 

pszAdDrvDvsLcl = ++pch; 

/* 

set addl drv.dev names 

*/ 


} 


/****************************************************** ************** ****** / 


/* */ 

/* now break the default driver.device_name string into two null */ 

/* terminated strings: */ 

/* default driver_name */ 

/* default device_name (or NULL if none) */ 

/* */ 


/**************************************************************************/ 


pszStart = pszDefDrvLcl ; 
pch = strchr(pszStart,’.’); 
if (pch!=NULL) 

{ 

*pch = ’\0*; 
pszDefDevLcl = ++pch; 

} 

} 

if (pszDefDrv!=NULL) 

*pszDefDrv = pszDefDrvLcl; 
if (pszDefQ!=NULL) 

*pszDefQ = pszDefQLcl ; 
if (pszAddlQs!=NULL) 

*pszAddlQs = pszAddlQsLcl ; 
if (pszAdDrvDvs!=NULL) 

*pszAdDrvDvs = pszAdDrvDvsLcl ; 
if (pszDefDev!=NULL) 

*pszDefDev = pszDefDevLcl ; 


/* initialize pointer */ 
/* find ’, 'separator */ 
/* if separator exists */ 

/* null terminate string */ 
/* set def device name */ 

/* set return default driver name */ 
/* set return default queue name */ 
/* set return addl queue names */ 
/* set return addl driver.device names */ 
/* set return default device name */ 


return(pszPort); 

} 


Figure 12.6 (continued) 
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/* 

BOOL 


PostDeviceModes( 


HAB hab 

PDRIVDATA FAR* pdrivDataRet 
PSZ pszDriver 
PSZ pszDevice 
PSZ pszPrinter 


postdevm.c */ 


{ 

/* Return the DRIVDATA structure for the specified driver, device and */ 
/* printer using DevPostDeviceModes. */ 
/* */ 
/* inputs: hab Anchor block handle */ 
/* pszDriver Driver name */ 
/* pszDevice Device name */ 
/* pszPrinter Printer name */ 
/* */ 
/* outputs: pdrivDataRet DRIVDATA structure */ 
/* */ 
/* It is the responsibi1ity of the caller to free the memory associated with */ 
/* the returned DRIVDATA structure. */ 
/* e.g. fRet = PostDeviceModes(..&pdrivData ..); */ 
/* */ 
/* free(pdrivData); */ 


LONG 1 Length 


/* 

DRIVDATA length 

*/ 

BOOL fRet = FALSE 


/* 

BOOL return code 

*/ 

PDRIVDATA pdrivData = NULL 


/* 

DRIVDATA pointer 

*/ 

*pdrivDataRet = NULL; 


/* 

initialize DRIVDATA 

pointer*/ 



/* 

post device modes 

*/ 

1 Length = DevPostDeviceModes( 

hab 

/* 

-anchor block handle 

*/ 

, 

NULL 

/* 

-DRIVDATA pointer 

*/ 

, 

pszDriver 

/* 

-driver name 

*/ 

, 

pszDevice 

/* 

-device name 

*/ 

, 

pszPrinter 

/* 

-printer name 

*/ 

) 

DPDM_CHANGEPROP 

/* 

-options 

*/ 


if (1 Length!=DPDM_ERROR && 1 Length!=DPDM_N0NE) 


pdrivData = mal1oc((SHORT)lLength); 

/* 

allocate DRIVDATA memory 

*/ 

if (pdrivData!=NULL) 

/* 

query default printer name 

*/ 

fRet = DevPostDeviceModes( hab 

/* 

-anchor block handle 

*/ 

, pdrivData 

/* 

-DRIVDATA pointer 

*/ 

, pszDriver 

/* 

-driver name 

*/ 

, pszDevice 

/* 

-device name 

*/ 

, pszPrinter 

/* 

-printer name 

*/ 

, DPDM CHANGEPROP 

/* 

-options 

*/ 

) != DPDM_ERROR; 




if (fRet) 

/* 

if no error 

*/ 

* p d rivDataRet = pdrivData; 

/* 

set returned PDRIVDATA 

*/ 

else 

/* 

el se 

*/ 

free(pdrivData); 

/* 

free memory 

*/ 


return(fRet); 

} 


Figure 12.7 PostDeviceModes Function. 
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/* qdefqueu.c */ 

PSZ QueryDefaultQueue(VOID) 

{ 


/* Return 

the default printer queue name. 


*/ 

/* 




*/ 

/* returns: PSZ Default printer queue name or 

NULL (error or not found). 

*/ 

/* 

This function null terminates the 

string (removing ’;’). 

*/ 

/* 




*/ 

/ * It is 

the responsibi1ity of the caller to 

free the memory associated with 

*/ 

/* the returned default queue name. 


*/ 

/* e . g . 

pszString = QueryDefaultQueue(); 


*/ 

/* 




*/ 

/* 

free(pszString); 



*/ 

PCHAR 

pch 


/* CHAR pointer 

*/ 

ULONG 

ulLength 


/* profile string size 

*/ 

BOOL 

fRet 


/* BOOL return code 

*/ 

LONG 

1 RetLen = 0L 


/* returned length 

*/ 

PSZ 

pszPrfStr = NULL 


/* profile string 

*/ 

PSZ 

pszQName = NULL 


/* default queue name 

*7 




/* query name string size 

*/ 

fRet = 

PrfQueryProfi1eSize( HINI_PR0FILE 

/* -INI file handle 

*/ 



“PM SPOOLER” 

/* -application name 

*/ 



“QUEUE” 

/* -key name 

*/ 



&ulLength 

/* -returned data length 

*/ 


); 


if (fRet && ulLength!=0) 


pszPrfStr = mal1oc((SHORT)ulLength); 

/* 

allocate memory for string 

*/ 

if (pszPrfStr !=NU.LL) 


/* 

query default queue name 

*/ 

IRetLen = PrfQueryProfi1eString( 

HINI PROFILE 

/* -INI file handle 

*7 


, “PM_SP00LER” 

/* -application name 

*/ 


, “QUEUE” 

/* 

-key name 

*/ 


9 

/* 

-default string 

*/ 


, pszPrfStr 

/* 

-returned string 

*/ 


, ulLength 

/* 

-max string length 

*/ 

if (IRetLen!=0) 

r 

) , 

/* 

if string returned 

*/ 

1 

pch = strchr(pszPrfStr , ’ ; ' ) ; 


/* 

find string end 

*/ 

if (pch!=NULL && pch!=pszPrfStr) 
/ 


/* 

if name exists 

*/ 

i 

pszQName = pszPrfStr; 


/* 

set name pointer 

*/ 

*pch = ’\0’; 

} 


/* 

null terminate string 

*/ 

J 

if (pszQName==NULL) 


/* 

if error 

*/ 

free(pszPrfStr); 


/* 

free memory 

*/ 


return(pszQName); 

} 


Figure 12.8 QueryDefaultQueue Function. 
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/* 



qqnames.c 

*/ 

PSZ QueryQueueNames(VOID) 

/ 




l 

/* Return the print queue names. 



*/ 

/* 




*/ 

/* returns: PSZ Print queue names or NULL 

(error or none found). 

*/ 

/* 

Note that each name is null terminated 

with the final name 

*/ 

/* 

/ * 

terminated by two nulls. 



*/ 

/* It is 

the responsibility of the caller 

to free the memory associated with 

*/ 

*/ 

/* the returned queue names. 



*/ 

/* e.g. 

pszString = QueryQueueNames(); 



*/ 

/* 




*/ 

/* 

free(pszString); 



*/ 

ULONG 

ulLength ; 

/* 

profile string size 

*/ 

BOOL 

fRet ; 

/* 

BOOL return code 

*/ 

LONG 

1 RetLen = OL ; 

/* 

returned length 

*/ 

PSZ 

pszPrfStr = NULL ; 

/* 

profile string 

*/ 

PSZ 

pszQNames = NULL ; 

/* 

queue names 

*/ 



/* 

query name string size 

*/ 

fRet = 

PrfQueryProfileSizeC HINI PROFILE 

/* 

-INI file handle 

*/ 


, “PM SPOOLER 

QUEUE” /* 

-application name 

*/ 


. NULL 

/* 

-key name 

*/ 


, &ulLength 

/* 

-returned data length 

*/ 


) ; 


if (fRet && ulLength!=0) 

pszPrfStr = ma11oc((SHORT)ulLength); /* allocate memory for string */ 


if (pszPrfStr!=NULL) 


/* 

query printer names 

*/ 

IRetLen = PrfQueryProfi1eString( 

HINI PROFILE 

/* -INI file handle 

*/ 


, “PM_SP00LER_ 

QUEUE” /* -appl. name 

*/ 


, NULL 

/* 

-key name 

*/ 


a ft 

/* 

-default string 

*/ 


, pszPrfStr 

/* 

-returned string 

*/ 


, ulLength 
); 

/* 

-max string length 

*/ 

if (1 RetLen! =0 && *pszPrfStr! = ’\0’ 

) 

/* 

if first name exists 

*/ 

pszQNames = pszPrfStr; 


/* 

set queue names pointer 

*/ 

if (pszQNames==NULL) 


/* 

if error 

*/ 

free(pszPrfStr); 


/* 

free memory 

*/ 


return(pszQNames); 

} 


Figure 12.9 QueryQueueNames Function. 
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/* qqdriver.c */ 

PSZ QueryQueueDriver(PSZ pszQueue, PSZ FAR* pszDevice) 

{ 


/* Return the name of the default driver for the specified queue. */ 
/* */ 
/* inputs: pszQueue Queue name. */ 
/* */ 
/* outputs: pszDevice Device name. */ 
/* */ 
/* returns: PSZ Driver name or NULL (error or not found). */ 
/* This function null terminates the string removing the or */ 
/* */ 


/* It is the responsibility of the caller to free the memory associated with */ 
/* the returned default printer name. */ 


/* e . g . 
/* 

/* 

pszString = QueryQueueDriver(..); 



*/ 

*/ 

*/ 

free(pszString); 




PCHAR 

pch 


/* 

CHAR pointer 

*/ 

ULONG 

ulLength 


/* 

profile string size 

*/ 

BOOL 

fRet 


/* 

BOOL return code 

*/ 

LONG 

1RetLen = OL 


/* 

returned length 

*/ 

PSZ 

pszPrfStr = NULL 


/* 

profile string 

*/ 

PSZ 

pszDriver = NULL 


/* 

driver name 

*/ 

*pszDevice = NULL; 


/* 

initialize device pointer 

*/ 




/* 

query name string size 

*/ 

fRet = 

PrfQueryProfileSize( HINI_P RO FILE 

/* 

-INI file handle 

*/ 



, “PM_SPOOLER_QUEUE_ 

DD’ 

7* -appl i cati on name 

*/ 



, pszQueue 

/* 

-key name 

*/ 



, &ulLength 

/* 

-returned data length 

*/ 


); 


if (fRet && ulLength!=0) 

pszPrfStr = mal1oc((SHORT)ulLength) ; 


/* allocate memory for string */ 


if (pszPrfStr!=NULL) /* query default driver name */ 
IRetLen = PrfQueryProfi1eString( HINI_PROFILE /* -INI file handle */ 

, “PM_SPOOLER_QUEUE_DD” /* -app. name */ 
, pszQueue /* -key name */ 
, /* -default string */ 
, pszPrfStr /* -returned string */ 
, ulLength /* -max string length */ 
); 


if (!RetLen!=0) 

/ 

/* 

if string returned 

*/ 

1 

pch = strchr(pszPrfStr , , ; > ); 

/* 

find string end 

*/ 

if (pch!=NULL && pch!=pszPrfStr) 

/ 

/* 

if driver name exists 

*/ 

i 

pszDriver = pszPrfStr; 

/* 

set driver name pointer 

*/ 

*pch = ’\0’; 

/* 

null terminate string 

*/ 

pch = strchr(pszPrfStr,’.’); 

/* 

find string end 

*/ 

if (pch!=NULL) 

/* 

if device exists 

*/ 

*pch = 70’ ; 

/* 

null terminate string 

■*/ 

*pszDevice = ++pch; 

/* 

set device pointer 

*/ 


) 

} 


Figure 12.10 QueryQueueDriver Function. 
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/* if error * / 

/* free memory */ 

return(pszDriver); 

} 


if (pszDriver==NULL) 
free(pszPrfStr); 


Figure 12.10 (continued) 


/* 



qqdrivda.c 

*/ 

PDRIVDATA 

r 

QueryQDriverData(PSZ pszQueue) 




1 

/* Return 

the DRIVDATA structure for the default driver of the specified 

*/ 

/* queue. 




*/ 

/* 




*/ 

/* inputs 

: pszQueue Queue name. 



*/ 

/* 




*/ 

/* returns: PDRIVDATA pointer to DRIVDATA 

structure 

or NULL (error or none). 

*/ 

/* 




*/ 

/* It is 

the responsibility of the caller 

to free the memory associated with 

*/ 

/* the returned DRIVDATA structure. 



*/ 

/* e.g. 

pdrivData = QueryQDriverData(..) 

; 


*/ 

/* 




*/ 

/* 

free(pdrivData); 



*/ 

ULONG 

ulLength ; 

/* 

profile string size 

*/ 

BOOL 

fRet ; 

/* 

BOOL return code 

*/ 

LONG 

1 RetLen = OL 

/* 

returned length 

*/ 

PDRIVDATA pdrivData = NULL ; 

/* 

DRIVDATA structure 

*/ 



/* 

query string size 

*/ 

fRet = 

PrfQueryProfi1eSize( HINI PROFILE 

/* 

-INI file handle 

*/ 


, “PM_SPOOLER_ 

QUEUE_DDDATA”/* -application name 

*/ 


, pszQueue 

/* 

-key name 

*/ 


, &ulLength 

/* 

-returned data length 

*/ 


); 


if (fRet && ulLength!=0) 


pdrivData = mal1oc((SHORT)ulLength); 

/* 

allocate memory for string 

*/ 

if (pdrivData!=NULL) 


/* 

query DRIVDATA structure 

*/ 

IRetLen = PrfQueryProfi1eString( 

HINI PROFILE 

/* -INI file handle 

*/ 


, “P M_S POOLE R_( 

3UEUE_DDDATA” /* -app. name 

*/ 


, pszQueue 

/* 

-key name 

*/ 


** 99 

/* 

-default string 

*/ 


, pdrivData 

/* 

-returned string 

*/ 


, ulLength 

'i. 

/* 

-max string length 

*/ 

if (1 RetLen==0) 

/ 

) , 

/* 

if no string returned 

*/ 

i 

free(pdrivData ) ; 


/* 

free memory 

*/ 

pdrivData = NULL; 


/* 

set return value = NULL 

*/ 


} 

return(pdrivData); 

} 


Figure 12.11 QueryQDriverData Function. 
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/* 

VOID PostJobProperties( 


HAB hab 

PDRIVDATA pdrivData 
PSZ pszDriver 
PSZ pszDevice 


postjobp.c */ 


/* Post a Job Properties dialog and return the supplied DRIVDATA structure */ 
/* modified by the end user selections. Note that this method of using */ 
/* DevPostDeviceModes may not be supported by all drivers. If an error is */ 
/* logged it can be ignored and is reset by this function before returning. */ 
/* The original DRIVDATA structure can still be used unmodified. */ 
/* */ 


/* inputs: 

hab 

Anchor block handle 



*/ 

/* 

pszDriver 

Driver name 



*/ 

/* 

pszDevice 

Device name 



*/ 

/* 

pdrivData 

DRIVDATA structure 



*/ 

/* 





*/ 

/* outputs: 

pdrivData 

DRIVDATA structure 

modified by end user 

*/ 

/* 





*/ 




/* 

post device modes 

*/ 

DevPostDeviceModes( 

hab 

/* 

-anchor block handle 

*/ 



pdrivData 

/* 

-DRIVDATA pointer 

*/ 



pszDriver 

/* 

-driver name 

*/ 



pszDevice 

/* 

-device name 

*/ 



NULL 

/* 

-printer name 

*/ 


) 

DPDM POSTJOBPROP 

/* 

-options 

*/ 

WinGetLastError(hab) 


/* 

reset error (i.e. ignore it if 

*/ 




/* 

not supported by this driver) 

*/ 


return; 

} 


Figure 12.12 PostJobProperties Function. 
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/* 

BOOL PrintDefPrinter(HAB hab) 

{ 

/* Print Gpi graphics to the default printer. 

//define PDOCNAME “Print Job” 

//define PDOCNAME LEN ( LONG) s i zeof ( PDOCNAME) 
//define PRINTTEXTP “Hello World” 

//define PRI NTTEXTP LEN ( LONG)(si zeof ( PRI NTTEXTP)-1) 


PSZ 

pszPrinter 

/* 

default printer 


*/ 

PSZ 

pszDefQ 

/* 

default printer queue 


*/ 

PSZ 

pszDefDrv 

/* 

default printer driver 

name 

*/ 

PSZ 

pszDefDev 

/* 

default printer device 

name 

*/ 

PDRIVDATA 

pdrivData 

/* 

pointer to DRIVDATA structure 

*/ 

DEVOPENSTRUC 

dopData 

/* 

DEVOPENSTRUC structure 


*/ 

SIZEL 

si zl 

/* 

PS size 


*/ 

POINTL 

ptlPoint 

/* 

coordinate point 


*/ 

LONG 

1 Length 

/* 

1ength 


*/ 

USHORT 

usJobld 

/* 

job id 


*/ 

PSZ 

pszPort = NULL 

/* 

port name 


*/ 

HDC 

hdc = DEV ERROR 

/* 

DC handle 


*/ 

BOOL 

fRetA = FALSE 

/* 

BOOL return code 


*/ 

BOOL 

fRet = FALSE 

/* 

BOOL return code 


*/ 

HPS 

hps = GPI_E RRO R 

/* 

PS handle 


*/ 

pszPrinter= 

Query DefaultPrinterO; 

; /* 

query default printer i 

name 

*/ 


if (pszPrinter!=NULL); 


/* 

Query 

port, queue, driver and device 

*/ 

pszPort= QueryPrinterInfo( 

pszPrinter 

/* 

printer name 

*/ 



&pszDefQ 

/* 

returned queue name address 

*/ 



&pszDefDrv 

/* 

returned driver name address 

*/ 



&pszDefDev 

/* 

returned device name address 

*/ 



NULL 

/* 

additional queues 

*/ 


) 

NULL 

/* 

addl driver.device names 

*/ 

if (pszPorti=NULL); 



/* 

post device modes 

*/ 

fRet = PostDeviceModes( 

hab 

/* 

-anchor block handle 

*/ 

, 

&pdrivData 

/* 

-DRIVDATA 

*/ 

, 

pszDefDrv 

/* 

-driver name 

*7 

, 

pszDefDev 

/* 

-device name 

*/ 


pszPrinter 

/* 

-printer name 

*/ 

j , 



/* 

set DevOpenDC params 

*/ 

dopData.pszLogAddress 

= 

pszDefQ; 

/* 

-logical address 

*/ 

dopData.pszDriverName 

= 

pszDefDrv; 

/* 

-driver name 

*/ 

dopData.pdriv 

= 

pdrivData; 

/* 

-DRIVDATA 

*/ 

dopData.pszDataType 

= 

“PM_Q_STD” 

; /* 

-data type 

*/ 

dopData.pszComment 

= 

“Gpi Printing”; 

/* -comment 

*/ 

dopData.pszQueueProcName 

= 

NULL; 

/* 

-queue proc name (default) 

*/ 

dopData.pszQueueProcParams 

= 

o 

o 

1— 
II 

o 

X 

~n 

3 

=0" ;/* 

' -queue proc params 

*/ 

dopData.pszSpoolerParams 

= 

NULL; 

/* 

-spooler params 

*/ 

dopData.pszNetworkParams 

= 

NULL; 

/* 

-network params (not used) 

*/ 


Figure 12.13 PrintDefPrinter Function. 


prtdefpr.c */ 
*/ 
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if (fRet) 


/* 

open an 0D_QUEUED DC 

*/ 

hdc = DevOpenDC( 

hab 

/* 

-anchor block handle 

*7 

, 

0D_QUEUED 

/* 

-DC type 

*/ 

, 


/* 

-token 

*/ 

, 

9L 

/* 

-number of data elements 

*/ 


(PDEVOPENDATA)&dopData 

/* 

-open DC data 

*/ 

) 

NULL 

/* 

-compatible DC handle 

*/ 

free(pszPrinter); 


/* 

free memory 

*/ 

free(pszPort); 


/* 

free memory 

*/ 

free(pdrivData); 


/* 

free memory 

*/ 

sizl.cx = 10000L; 
sizl.cy = 10000L; 
if(hdc!=DEV_ERR0R) 


/* 

create PS 

*/ 

hps = GpiCreatePS( hab 

/* 

-anchor block handle 

*/ 


, hdc 

/* 

-DC handle 

*/ 


, & s i z 1 

/* 

-PS size 

*/ 


, PU_ARBITRARY 

/* 

options 

*/ 


y r u_nr\u i i r\nr\ i 

GPIF_DEFAULT 
GPIA_NOASSOC 
GPIT_NORMAL 


); 

if (hps!=GPI_ERROR) /* associate PS and DC */ 

fRetA = GpiAssociate(hps, hdc); 

1 Length = OL; 


if (fRetA) 


/* 

issue start document DevEscape 

*/ 

fRet = DevEscape( 

hdc 

/* 

-DC handle 

*/ 


DEVESC STARTDOC 

/* 

-escape code 

*/ 


PDOCNAMELEN 

/* 

-size of document name 

*/ 


PDOCNAME 

/* 

-null terminated document name 

*/ 


&1Length 

/* 

-size of output data (OL) 

*/ 


NULL 

/* 

-output data (not used 

*/ 


) === DEV_0K; 

else 

fRet = FALSE; 

ptlPoint.x = 1000 L; 
ptlPoint.y = 1000L; 

if (fRet) /* draw to the printer */ 

fRet = (BOODGpi CharStri ngAt ( hps 

, &ptlPoint 
, PRINTTEXTPLEN 
, PRINTTEXTP 


1 Length = 2L; 
if(fRet) 


/* 

issue end document DevEscape 

*/ 

fRet = DevEscape( 

hdc 

/* 

-DC handle 

*/ 

, 

DEVESC ENDDOC 

/* 

-escape code 

*/ 

, 

OL 

/* 

-length of input data (OL) 

*/ 

, 

NULL 

/* 

-input data (not used) 

*/ 

, 

&1Length 

/* 

-size of output data (2L) 

*/ 

, 

(PBYTE)&usJobId 

/* 

-output data (returned job id) 

*/ 


) == DEV_0K; 


Figure 12.13 (continued) 
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if(fRetA) 

fRet = GpiAssociate(hps , NULL) && fRet; /* dissociate PS and DC */ 

if(hps!=GPI_ERR0R) 

fRet = GpiDestroyPS(hps) && fRet; /* destroy PS */ 

if(hdc!=DEV_ERR0R) 

fRet = DevCloseDC(hdc) != DEV_ERR0R && fRet; /* close DC */ 

return(fRet); 


Figure 12.13 (continued) 


/* 

BOOL PrintDefQueueCHAB hab, ULONG ulPostDialog) 


prtdefqu.c */ 


Print Gpi graphics to the default print queue. Optionally post a job 
properties dialog. 


/* inputs: hab Anchor block handle 

/* ulPostDialog Options : (0) Do not post Job Properties Dialog 

/* (1) Post Job Properties Dialog 

/* Note that not all drivers support a Job Properties Dialog in this mode. 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


#define 

QDOCNAME 

"Print Job" 





#define 

QDOCNAMELEN 

(LONG)sizeof(QDOCNAME) 



#define 

PRINTTEXTQ 

"Hel1o World” 





#define 

PRINTTEXTQLEN 

(LONG)(sizeof(PRINTTEXTQ)-1) 



PDRIVDATA 

pdrivData 

= NULL 

/* 

pointer to DRIVDATA 

structure 

*/ 

PSZ 

pszDevice 


/* 

device name 


*/ 

DEVOPENSTRUC dopData 


/* 

DEVOPENSTRUC structure 

*/ 

SIZEL 

s i z 1 


/* 

PS size 


*/ 

POINTL 

ptlPoint 


/* 

coordinate point 


*/ 

LONG 

1 Length 


/* 

1ength 


*/ 

USHORT 

usJobld 


/* 

returned job id 


*/ 

PSZ 

pszQueue 

= NULL 

/* 

queue name 


*/ 

PSZ 

pszDriver 

= NULL 

/* 

driver name 


*/ 

HDC 

hdc 

= DEV ERROR 

/* 

DC handle 


*/ 

BOOL 

f RetA 

= FALSE 

/* 

BOOL return code 


*/ 

BOOL 

fRet 

= FALSE 

/* 

BOOL return code 


*/ 

LONG 

1 Ret 

= DPDM ERROR 

/* 

LONG return code 


*/ 

HPS 

hps 

= GPI ERROR 

/* 

PS handle 


*/ 

pszQueue= 

QueryDefaultQueue(); 

/* 

query default queue 

name 

*/ 


Figure 12.14 PrintDefQueue Function. 
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if (pszQueue!=NULL) 


/* 

query driver and device names 

*/ 

pszDriver = QueryQueueDriver( pszQueue 

/* 

-queue name 

*/ 


, &pszDevice 

/* 

-device name 

*/ 

if (pszDriver!=NULL) 

), 




pdrivData = QueryQDriverData(pszQueue); 

/* 

query DRIVDATA 

*/ 

if (pdrivData!=NULL) 

/ 




1 Ret - DEV_OK; 







/* 

Post Job Properties Dialog if 

*/ 

if (ulPostDialog) 


/* 

this option is requested 

*/ 

1 Ret = DevPostDeviceModes( hab 

/* 

-anchor block handle 

*/ 


, pdrivData 

/* 

-DRIVDATA pointer 

*/ 


, pszDriver 

/* 

-driver name 

*/ 


, pszDevice 

/* 

-device name 

*/ 


, NULL 

/* 

-printer name 

*/ 


, DPDM POSTJOBPROP/* -options 
); 

*/ 

} 


/* 

set DevOpenDC params 

*/ 

dopData.pszLogAddress = pszQueue; 

/* 

-logical address 

*/ 

dopData.pszDriverName = pszDriver; 

/* 

-driver name 

*/ 

dopData.pdriv 

= pdrivData; 

/* 

-DRIVDATA 

*/ 

dopData.pszDataType 

= “PM_Q_STD”; 

/* 

-data type 

*/ 

dopData.pszComment 

= “Gpi Printing”;/ 

* -comment 

*/ 

dopData.pszQueueProcName = NULL; 

/* 

-queue proc name (default) 

*/ 

dopData.pszQueueProcParams = n C0L=C XFM=0 H ; 

/* 

-queue proc params 

*/ 

dopData.pszSpoolerParams = NULL; 

/* 

-spooler params 

*/ 

dopData.pszNetworkParams = NULL; 

/* 

-network params (not used) 

*/ 

if (1 Ret!=DPDM_ERR0R) 

/* 

open an 0D_QUEUED DC 

*/ 

hdc = DevOpenDC( hab 

/* 

-anchor block handle 

*/ 

, 0D_QUEUED 

/* 

-DC type 

*/ 

9 

"k 99 

/* 

-token 

*/ 

, 9 L 

/* 

-number of data elements 

*/ 

, (PDEVOPENDATA)&dopData 

/* 

-open DC data 

*/ 

, NULL 
); 

/* 

-compatible DC handle 

*/ 

free(pszQueue); 


/* 

free memory 

*/ 

free(pszDriver); 


/* 

free memory 

*/ 

free(pdrivData ) ; 


/* 

free memory 

*/ 

sizl.cx = 10000L; 





sizl . cy = 10000L; 





if(hdc!=DEV_ERR0R) 


/* 

create PS 

*/ 

hps = GpiCreatePS( hab 

/* 

-anchor block handle 

*/ 


hdc 

/* 

-DC handle 

*/ 


&si zl 

/* 

-PS size 

*/ 


PU ARBITRARY 

/* 

options 

*/ 


GPIF DEFAULT 





GPIA NOASSOC 





GPIT_NORMAL 

; 




if (hps!=GPI_ERR0R) 





fRetA = GpiAssociate(hps, hdc); 

/* 

associate PS and DC 

*/ 


Figure 12.14 (continued) 
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ptlPoint.x = 1000L; 
ptlPoint.y = 1000 L; 
1 Length = 0 L; 


if (fRetA) 

/* 

issue start document DevEscape 

*/ 

fRet = DevEscape( hdc 

/* 

-DC handle 

*/ 

, DEVESC STARTDOC 

/* 

-escape code 

*/ 

, QDOCNAMELEN 

/* 

-size of document name 

*/ 

, QDOCNAME 

/* 

-null terminated document name 

*/ 

, &1Length 

/* 

-size of output data (OL) 

*/ 

. NULL 

/* 

-output data (not used 

*/ 

) == DEV OK; 




if (fRet) 

/* 

draw to the printer 

*/ 


fRet = (BOODGpiCharStringAt( hps 

, &ptlPoint 
, PRINTTEXTQLEN 
, PRINTTEXTQ 
); 


1 Length = 2L; 




if(fRet) 


/* issue end document DevEscape 

*/ 

fRet = DevEscape( 

hdc 

/* -DC handle 

*/ 

, 

DEVESC ENDDOC 

/* -escape code 

*/ 

, 

OL 

/* -length of input data (OL) 

*/ 

, 

NULL 

/* -input data (not used) 

*/ 

, 

&1Length 

/* -size of output data (2L) 

*/ 

) 

(PBYTE)&usJobld 
== DEV_0K; 

/* -output data (returned job id) 

*/ 


if(fRetA) 

fRet = GpiAssociate(hps, NULL) && fRet; /* dissociate PS and DC */ 

if(hps!=GPI_ERR0R) 

fRet = GpiDestroyPS(hps) && fRet; /* destroy PS */ 

if(hdc!=DEV_ERR0R) 

fRet = DevCloseDC(hdc) != DEV_ERR0R && fRet; /* close DC */ 

return(fRet); 


Figure 12.14 (continued) 
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/* printraw.c */ 

BOOL PrintRawData(HAB hab) 

{ 

/* Print raw data to the default printer. */ 

^define RDOCNAME “Print Job” 

^define RDOCNAMELEN (LONG)sizeof(RDOCNAME) 

^define RAWDATA “Raw Data Raw Data Raw Data Raw Data Raw Data” 

^define RAWDATALEN (LONG)sizeof(RAWDATA) 


PSZ 

pszPrinter 


/* 

default printer 

*/ 

PSZ 

pszDefQ 


/* 

default printer queue 

*/ 

PSZ 

pszDefDrv 


/* 

default printer driver name 

*/ 

PSZ 

pszDefDev 


/* 

default printer device name 

*/ 

PDRIVDATA 

pdrivData 


/* 

pointer to DRIVDATA structure 

*/ 

DEVOPENSTRUC 

dopData 


/* 

DEVOPENSTRUC structure 

*/ 

LONG 

1 Length 


/* 

1ength 

*/ 

USHORT 

usJobld 


/* 

job id 

*/ 

PSZ 

pszPort 

= NULL 

/* 

port name 

*/ 

HDC 

hdc 

= DEV ERROR 

/* 

DC handle 

*/ 

BOOL 

fRet 

= FALSE 

/* 

BOOL return code 

*/ 

pszPrinter= 

QueryDefaultPrinter(); 

/* 

query printer name 

*/ 


if (pszPrinter!=NULL); /* query port, queue, driver and device */ 


pszPort= QueryPrinterlnfoC pszPrinter 

/* -printer name 

*/ 


, &pszDefQ 

/* -returned queue name address 

*/ 


, &pszDefDrv 

/* -returned driver name address 

*/ 


, &pszDefDev 

/* -returned device name address 

*/ 


, NULL 

/* -additional queues 

*/ 


, NULL 
); 

/* -addl driver.dev ice names 

*/ 

if (pszPort!=NULL); 


/* post device modes 

*/ 

fRet = PostDeviceModes( 

hab 

/* -anchor block handle 

*/ 

, 

&pdrivData 

/* -DRIVDATA 

*/ 

, 

pszDefDrv 

/* -driver name 

*/ 

, 

pszDefDev 

/* -device name 

*/ 

>. 

pszPrinter 

/* -printer name 

*/ 

), 


/* set DevOpenDC params 

*/ 

dopData.pszLogAddress 

= pszDefQ; 

/* -logical address 

*/ 

dopData.pszDriverName 

= pszDefDrv; 

/* -driver name 

*/ 

dopData.pdriv 

= pdrivData; 

/* -DRIVDATA 

*/ 

dopData.pszDataType 

= “PM_Q_RAW”; 

/* -data type 

*/ 

dopData.pszComment 

= “Raw Data”; 

/* -comment 

*/ 

dopData.pszQueueProcName 

= NULL; 

/* -queue proc name (default) 

*/ 

dopData. pszQueueProcParams 

i = NULL; 

/* -queue proc params 

*/ 

dopData.pszSpoolerParams 

= NULL; 

/* -spooler params 

*/ 

dopData.pszNetworkParams 

= NULL; 

/* -network params (not used) 

*/ 

if (fRet) 


/* open an 0D_QUEUED DC 

*/ 

hdc = DevOpenDC( hab 


/* -anchor block handle 

*/ 

, 0D_QUEUED 

/* -DC type 

*/ 

•** ” 


/* -token 

*/ 

; 9 l 


/* -number of data elements 

*/ 

, (PDEVOPENDATA)&dopData 

/* -open DC data 

*/ 

, NULL 


/* -compatible DC handle 

*/ 


); 


Figure 12.15 PrintRawData Function. 
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free(pszPrinter); /* free printer name memory */ 

free(pszPort); /* free port name etc. memory */ 

free(pdrivData); /* free DRIVDATA memory */ 

1 Length = OL; 

if(hdc!=DEV_ERR0R) /* issue start document DevEscape */ 

fRet = DevEscape( hdc /* -DC handle */ 

, DEVESC_STARTDOC /* -escape code */ 

, RDOCNAMELEN /* -size of document name */ 

, RDOCNAME /* -null terminated document name */ 

, &1Length /* -size of output data (OL) */ 

, NULL /* -output data (not used */ 

) == DEV_0K; 

else 

fRet = FALSE; 


1 Length = OL; 

if(fRet) /* issue raw data DevEscape */ 

fRet = DevEscape( hdc /* -DC handle */ 

, DEVESC_RAWDATA /* -escape code */ 

, RAWDATALEN /* -length of raw data */ 

, RAWDATA /* -raw data */ 

, &1Length /* -size of output data (OL) */ 

, NULL /* -output data (not used) */ 

) == D E V_0 K; 

1 Length = 2L; 

if (fRet.) /* issue end document DevEscape */ 

fRet = DevEscape( hdc /* -DC handle */ 

, DEVESC_ENDDOC /* -escape code */ 

, OL /* -length of input data (OL) */ 

, NULL /* -input data (not used) */ 

, &1Length /* -size of output data (2L) */ 

, (PBYTE)&usJobld /* -output data (returned job id) */ 

) == DEV_0K; 

if(hdc!=DEV_ERROR) 

•fRet = DevCl oseDC (hdc) != DEV_ERR0R && fRet; /* close the DC */ 


return(fRet); 

} 


Figure 12.15 (continued) 
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/* qryqproc.c */ 

PSZ QueryQueueProcessors(V01D) 

{ 

/* Return the print queue processor names. */ 

/* */ 

/* returns: PSZ Print queue processor names or NULL (error or not found). */ 

/* Note that each name is null terminated with the final name */ 

/* terminated by two nulls. */ 

/* */ 

/* It is the responsibility of the caller to free the memory associated with */ 
/* the returned print queue processor names. */ 

/* e.g. pszString = QueryQueueProcessors(); */ 

/* . */ 
/* free(pszString); */ 


ULONG 

ulLength 


BOOL 

fRet 


LONG 

1 RetLen 

= OL 

PSZ 

pszPrfStr 

= NULL 

PSZ 

pszQProcs 

= NULL 


/* profile string size */ 
/* BOOL return code */ 
/* returned length */ 
/* profile string */ 
/* queue processor names */ 


/* query queue string size */ 
fRet = PrfQueryProfi1eSize( HINI_PROFILE /* -INI file handle */ 

, “PM_SP00LER_QP” /* -application name */ 
, NULL /* -key name */ 
, &ulLength /* -returned data length */ 
); 


if (fRet && ulLength!=0) 

pszPrfStr = mal1oc((SHORT)ulLength); /* allocate memory for string */ 


if (pszPrfStr!= NULL) /* query queue names */ 
IRetLen = PrfQueryProfi1eString( HINI_PROFILE /* -INI file handle */ 

, “PM_SP00LER_QP” /* -application name */ 
, NULL /* -key name */ 
, /* -default string */ 
, pszPrfStr /* -returned string */ 
, ulLength /* -max string length */ 
); 


if (!RetLen!=0 && *pszPrfStr!=’\0') /* if first name exists */ 

pszQProcs = pszPrfStr; /* set queue names pointer */ 

if (pszQProcs==NULL) /* if error */ 

free(pszPrfStr); /* free memory */ 

return(pszQProcs); 


Figure 12.16 QueryQueueProcessors Function. 






The OS/2 2.0 32-Bit Operating System 


IBM has made no secret of its intention of providing OS/2 Version 2.0, the 32-bit 
version of the current operating system, and the IBM/Microsoft Software Devel¬ 
opment Kit (SDK) is already available. At the time of writing this book, much of 
the content of OS/2 Version 2.0 is well established. Although is not possible to say 
when this release will become available or what its exact content will be, with one 
or two exceptions, it can be assumed that the Presentation Manager functions are 
available (as described in this book) with the new 32-bit flat memory model API 
discussed below. The only change for the majority of the GPI functions is a change 
to the precise meaning of any pointers (this is frequently hidden by the compiler). 

OS/2 Version 2.0jprovides a-binarv co mpatible 16-bit API for us e with new a nd 
existing 16-bit_ ap plication s. All program examples provided in this book should 
therefore continue to operate successfully using the Version 2.0 16-bit API. 

In addition, it provi des a 32-bit flat memory model API that hides the segmen¬ 
tation from the programmer an d pr ovides addressing' via a 32-bit offset,Itreatihg 
all calls as near/This allows the system to exploit the 32-bit features of the Intel™ 
80386 pr oces sor, provides improved portability, and eliminates the 64K addressing 
limitations inherent in the segmented 16-bit memory model. Existing 16-bit 
applications may be converted to the new 32-bit API by flattening any 16-bit 
segment and offset operations and removing all Tar' references. The application 
must then be rebuilt using the new 32-bit language compiler and tools. 

For the majority of the programs in this book, removal of Tar' references, 
recompilation, and so forth, is all that is required. For other functions (e.g., the 
function DisplayPMError in chapter 1), segment and offset pointer operations 
must be modified to conform to the 32-bit flat memory model. 

Although the 16-bit API provides binary compatibility for all existing Presenta¬ 
tion Manager functions, a few of these existing functions may not be available with 
the 32-bit API, and some of these will be replaced by different (and better) 32-bit 
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functions. All 16-bit API functions, however, continue to be available to 32-bit 
Mixed Applications that elect to use both 32-bit and 16-bit APIs. The 32-bit API 
also provides some new functions and a number of enhancements to the original 
16-bit functions. 



APPENDIX 1 


DevOpenDC Parameters 


HDC PASCAL FAR DevOpenDC( HAB hab 

, LONG lType 
, PSZ pszToken 
, LONG ICount 
, PDEVOPENDATA pdopData 
, HDC hdcComp 
); 

hab 

This is the anchor block handle returned by Winlnitialize. 

IType 

This is the DC type and is specified as one of: 

OD_QUEUED; 

OD_DIRECT; 

OD_INFO; 

OD_METAFILE; 

OD_METAFILE_NOQUERY; and 

OD_MEMORY. 


2S7 
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pszloken 

This is intended to identify the device information to be taken from the INI file 
instead of from the pdopData parameter. This parameter is currently ignored and 
should be specified as indicating that no information should be taken from the 
INI file. 

ICount 

This is the number of pdopData elements provided. For a DC type of OD_MEM- 
ORY, this should be specified as zero. For other DC types, a value of up to nine can 
be specified. Values less than nine cause the omitted elements to be defaulted. 

pdopData 

This provides a variable number of additional DevOpenDC parameters. In theory, 
not all the elements are required in all cases but it is normally safer to provide the 
complete structure. For a DC type of OD_MEMORY, this should be specified as 
NULL as the hdcComp parameter identifies the driver and, thus, provides all the 
necessary information (see the note below for printers that support multiple 
resolutions). Otherwise, this parameter can be viewed as either: 

a pointer to a DEVOPENDATA structure 


or 


an array of PSZ (null terminated string pointers) as defined by 
PDEVOPENDATA where the third element is actually of type 
PDRIVDATA and must be typecast to PSZ. 

It is possible (using the ICount parameter above) to provide less 
than the maximum number of structure/array elements, allowing 
the remainder to be defaulted. In practice, however, as can be ob¬ 
served from the examples in this book, it is normally safer to pro¬ 
vide the complete structure. 

The pdopData structure (array elements) are as follows: 

pdopData.pszLogAddress (pdopData[ADDRESS]) 

For a DC of type OD_DIRECT, this is the logical device address or 
port name (e.g., “LFXT”, “COM1”). 

For a DC of type OD_QUEUED, this is the user specifiable queue 
name (e.g., “LPT1Q”, “COM1Q”). 

For a non-display DC of type OD_INFO, this is the logical device 
address or port name (e.g., “LPT1”, “COMl”)° 

For a display DC of type OD_INFO or for any other DC type, this 
should be specified as NULL. 



DEVOPENDC PARAMETERS 


259 


Port and queue names can be queried using Prf 1 Query Profile Str¬ 
ing (see chapter 12). 

pdopData.pszDriverName (pdopData[DRIVER_NAME]) 

For a DC of type ODJDIRECT, OD_QUEUED, or OD_INFO for a 
non-display device, this is the name of the presentation driver for 
which the DC is required (e.g., “IBM4019”, “LASERJET”). The corre¬ 
sponding driver (IBM4019.DRV, etc.) must be present in the path de¬ 
fined for that driver at installation time (i.e., as specified in the INI 
file). 

For a DC type of OD DIRECT for a display device, OD METAF- 
ILE or OD_METAFILE_N0_QUERY, this should be specified as 
“DISPLAY”. 

Driver names can be queried using Prf Query Profile String, which 
may return the driver name as the first part of a 
drivername.devicename string (see chapter 12). 

pdopData.pdriv (pdopData[DRIVER_DATA]) 

For a DC of type OD_DIRECT, OD_QUEUED, or OD_INFO, this 
is a pointer to a DRIVDATA structure. This may be specified in one 
of four different ways: 

1. For drivers without a dot qualified device name extension (e.g., 
IBM4019), this can be specified as NULL, although the alterna¬ 
tive methods below such as DevPostDeviceModes may be used 
if appropriate. For drivers that do have a dot qualified device 
name (e.g., PLOTTERS.IBM6180), one of the following methods 
must be used. 

2. A DRIVDATA structure specifying the device name may be 
built, as shown in the example below, by the application. 
However, this is not the recommended method as all printer and 
job properties will be defaulted. 

{ 

pdriv.cb” sizeof(DRIVDATA); 
pdriv.lVersion= OL; 

strcpy(pdriv.szDeviceName, “IBM6180”); 
abGeneralData[0] = 0x00; 

} 

3. A DRIVDATA structure can be obtained using 
DevPostDeviceModes. This method prompts the driver to use 
printer device and job options (e.g., portrait/landscape) stored 
previously in the INI file via the Print Manager dialogs and 
optionally allows these to be modified (and the INI file updated) 
from DevPostDeviceModes end user dialogs. 

4. A DRIVDATA structure can be built using PrfQueryProfileStr- 
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ing (Application name = “PM_S POOLERJ^UEXJEJDDDATA” 
Key name = Queue Name). This method uses printer job options 
set previously using the printer queue Print Manager dialog. 
These will override options set using the printer name Print 
Manager dialog. 

See chapter 12 for examples of the above. For other DC types, this 
parameter can be specified as NULL or omitted. This includes DCs 
of type OD_MEMORY but see the note below. 

pdopData.DataType (pdopData[DATA_TYPEj) 

For a DC of type OD_QUEUED (or a DC of type ODJ3IRECT re¬ 
quired to print a previously queued print file), this is the print file 
data type and can be one of the following: 

“PM_Q_STD” is the standard print spool file format that closely 
resembles a MetaFile. This is the recommended format and is the 
default if this parameter is not specified. In this format, the print 
file is fairly device independent but all system fonts required for 
printing must be installed as public fonts on the local workstation 
for local printing or on the print server for network printing. 

The intention of this format is to provide a device independent for¬ 
mat that enables printer pooling using different printers. Although 
this is theoretically possible, OS/2 is not currently enabled for this, 
allowing only printer pooling using printers of the same type. 

“PM_Q_RAW” is used for creating print files in device specific for¬ 
mat. In this format, print files are generally unsuitable for printing 
on devices other than that for which they were originally created (al¬ 
though in fact they may often contain ASCII text with device spe¬ 
cific escapes). The advantage of this format is that there is no re¬ 
quirement for system fonts to be available anywhere other than on 
the requesting process. Device fonts required for printing must, of 
course, be installed on the target device. Printer and job property di¬ 
alog selections are generally ignored for PM_Q_RAW format. 

Other Strings can be used to specify special formats unique to a 
particular print queue processor. 

For other DC types, or default, this parameter can be specified as 
NULL or omitted. 

pdopData.pszComment (pdopData[COMMENT]) 

For a DC of type OD_QUEUED, this is an optional natural lan¬ 
guage description of the job which, for a print job, may be displayed 
(using the Print Manager) together with other job details when the 
job is in the print queue. For a MetaFile DC, this description is 
stored in the MetaFile. 
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For other DC types, this parameter can be specified as NULL or 
omitted. 

pdopData.pszQueueProcName (pdopData[PROC_NAME]) 

For a DC of type OD_QUEUED, this parameter is the name of the 
print queue processor and should be defaulted for normal printing. 
The default is defined (using Print Manager setup) separately for 
each queue and is normally “PMPRINT”. For applications with no 
special requirements (and that, for example, are printing using the 
default queue), it should be possible to assume that the default 
queue processor is suitable for normal printing. This enables alter¬ 
native (compatible) queue processors to replace “PMPRINT” as a 
queue default and remain transparent to the application. Alterna¬ 
tively, for applications with special requirements, the name of the re¬ 
quired queue processor (installed via the Control Panel) can be speci¬ 
fied explicitly, or a queue with this queue processor selected as its 
default can be used. For example, an application may wish to use a 
special queue processor (e.g., PMPLOT) to perform the reverse clip¬ 
ping required for plotting. 

The installed queue processor names can be queried using 
PrfQueryProfileString (see chapter 12). 

For other DC types, or default, this parameter can be specified as 
NULL or omitted. 

pdopData.pszQueueProcParams (pdopData[PROC_PARAMS]) 

For a DC of type OD_QUEUED, this is an optional string of print 
queue processor parameters of the form “keyword=value key¬ 
word-value keyword-value”, with the individual parameters sepa¬ 
rated by spaces. Each queue processor may define its own require¬ 
ments for this parameter. PMPRINT is the default Presentation 
Manager print queue processor (see Appendix 2 for a description of 
the PMPRINT queue processor parameters). 

For other DC types or default, this parameter can be specified as 
NULL or omitted. 

pdopData.pszSpoolerParams (pdopData[SPL_PARAMS]) 

For a DC of type OD_QUEUED, this is an optional string of 
spooler queue manager parameters of the form “keyword=value key- 
word=value”, with the individual parameters separated by spaces. 
The valid keywords are ‘FORM=f/ and TRTY=xx/ 

FORM-f specifies the name of a valid form (as returned by 
DevQueryHardcopyCaps). Note that the job will not actually print 
unless the specified form is installed or one that is selectable with¬ 
out operator intervention. This should not be used if the 
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DRIVER_DATA field above contains a DRIVDATA structure re¬ 
turned by DevPostDeviceModes as this includes a form code. 

PRTY=xx specifies the job priority in the range 00-99 (highest=99, 
default=50). 


For other DC types or default, this parameter can be specified as 
NULL or omitted. 


pdopData.pszNetworkParams (pdopData[NETWORK_PARAMS]) 

This parameter is currently unused (even by IBM OS/2 Extended 
Edition) and should therefore be specified as NULL or omitted. 


hdc 

Bitmaps are always owned by a particular device and, for a DC type of OD_MEM- 
ORY, this is the handle of any existing DC of the device for which the ODJMEM- 
ORY DC is required. An OD_MEMORY DC thus created, is suitable for use with 
all DCs for the device, regardless of whether they are OD_QUEUED or ODJDI- 
RECT. 

For DC types other than OD_MEMORY, this parameter should be NULL. 

It was stated above that the pdopData (or DEVOPENPENDATA) parameter 
should be specified as NULL when opening an OD_MEMORY DC. Although this 
accurately reflects the API definition and works in the majority of cases, it does 
require qualification. When drawing to a bitmap owned by a print driver that 
supports a number of selectable resolutions (e.g., the IBM4Q19 driver supports 
resolutions of 300, 150, 100, and 75 pels per inch), the driver is currently unable 
to determine the correct resolution to use, and instead will use its own default. For 
example, if the page units of the PS associated with the bitmap OD_MEMORY 
memory DC are PU_LOENGLISH, a line 100 units long is drawn to the bitmap 
and GpiBitBlt is used to output the bitmap to the printer, a line of one inch should 
be printed. If the actual and driver default resolutions are the same, then the line 
will be correct. For example, if the default printer resolution is 150 and the actual 
resolution is 300, then the length of the printed line will be halved; if the actual 
resolution is 75, the length will be doubled. This problem does not apply when 
working with device units (i.e., PU_PELS) or when performing straightforward 
bitmap image operations. It is possible that this may eventually be corrected 
internally by changes to the drivers and device driver interface but presently, the 
recommended bypass (for some drivers) is to supply a DEVOPENSTRUC param¬ 
eter with a DRIVDATA structure providing the required resolution. 
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PMPRINT Queue Processor Parameters 


For a DC of type OD_QUEUED, this is an optional string of print queue processor 
parameters of the form w keyword=value keyword=value keyword=value”. For 
PMPRINT, the valid keywords are ‘COP=/ ‘ARE=/ TIT=/ < XFM=/ ‘XLT=/ and 
‘COL=/ Note that the ‘ARE= J and TIT=’ parameters operate on the page viewport 
that reflects the PS page dimensions converted to device coordinates. They will 
only therefore, give correct results if the PS page dimensions (specified on 
GpiCreatePS) accurately reflect the correct form size. This is not normally 
achieved by defaulting the PS page dimensions. Note that the PS page dimensions 
are less important if the ‘XFM-Q’ option is used. 

COP=n 

This specifies the number of copies n (n is an integer >=0). 

ARE= 


This specifies the size and position of the output area as follows: 

ARE=C specifies that the required output area is maximum size 
(i.e., equal to the size of maximum available output area) but does 
not imply that the output is scaled to fill it. 

ARE=w,h,l,t specifies the size and position of the required output 
area (where w,h are width, height and l,t are left and top offsets of 
the top left corner relative to the top left comer of the maximum 
available output area, all expressed as integer percentages of the 
maximum available output area). These are not particularly easy to 
use but the example in Figure A2-1 should help to illustrate their 
use. Other examples also appear in the IBM OS/2 Programming 
Guide. 
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"FIT=l,t" where l=a*100/Wreal, t=b*lGQ/Hreal 
"ARE=Wjh,1,t” where w®Wreq*100/Wm&x s h=Hreq*10Q/Hmax 
l=c*100/Wmax, t=d*100/Hmax 

Figure A2.1 Use of FIT= and ARE= Parameters 


FIT= 

This specifies the size and position of the actual output inside the 
output area requested (using ARE=) as follows: 

FIT=S specifies that the actual output (i.e., the PS page) 
should be scaled to fit the required output area (i.e., drawn as 
large as possible while retaining its aspect ratio such that a 
circle remains a circle). At least one dimension of the picture 
will completely fill the corresponding dimension of the required 
output area while the other dimension will be centered where 
applicable. 

The ‘scale to fit' option may not provide the required results 
in many cases (see below). 
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FIT=l,t specifies that the picture should be printed real size 
(i.e., not scaled) with its origin defined by 1 and t. These are the 
offsets of the point in the real size output (or presentation page) 
that is to appear at the center of the required output area 
(defined by ARE=). The values are relative to the top left corner 
of, and are expressed as integer percentages of the real size 
output (or presentation page) dimensions. These are not partic¬ 
ularly easy to use but the example in Figure A2-1 should help 
to illustrate their use. Other examples also appear in the IBM 
OS/2 Programming Guide. 


COL= 

This specifies whether the picture should be output in color or 
(where supported) in different shades of gray (“COL=C”), or whether 
it should be output in monochrome (“COL~M”) with only a single 
foreground and background color. 

XFM= 

This specifies whether the output should be printed real size (i.e., 
as OD_DIRECT) ignoring the FIT= and ARE= parameters 
(“XFM=0”), or whether its position and size should be determined 
using the FIT= and ARE= parameters (”XFM=1”) as described above. 

XLT= 


As explained in chapter 7, when the resolution of the output de¬ 
vice is high compared to that of the PS page, (0,0) in world coordi¬ 
nates will not transform to (0,0) on the device; typically it might 
transform to (1,1). This does not normally present a problem unless 
a device happens to require every available pel in order to print a 
row of text containing the maximum possible number of characters. 
For such devices, this translation can cause the maximum number 
of characters printed horizontally to be reduced (e.g., to 79 from 80). 
In theory, a similar problem could also exist vertically but this is 
‘ less likely and has never been reported. This can be remedied by 
specifying “XLT=1”, which provides an additional translation to en¬ 
sure that (0,0) in the PS page transforms to (0,0) on the device. This 
occurs regardless of any other parameters (including “XFM=0”). 
“XLT=0” will not apply this correction. 

The default for PMPRINT is “COP=l ARE=C FIT=S XFM=1 XLT=0 COL=M” for 
a mono printer and “COP=l ARE=C FIT=S XFM=1 XLT=0 COL=C” for a color 
printer. Note that these defaults will not give the same results as printing to an 
OD_DIRECT DC. The most noticeable difference is that OD_QUEUED output is, 
by default, scaled to fit with one dimension centered. This default scaling may 
result in an incorrect size and might prevent a required font match from occurring. 

In addition, operations such GpiBitBlt that are specified using device coordi- 
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nates are unaffected by any scaling or translation arising from these parameters 
and are therefore likely to appear in the incorrect position relative to other output 
if the output is scaled to fit. This will occur unless these parameters are explicitly 
specified to force the output to be real size and positioned with its origin at the 
bottom left comer of the output area (i.e., XFM-0 XLT=1). This can also be 
achieved by defining the PS Page and page units to exactly reflect the size of the 
output area (or in the case of PU_ARBITRARY ensuring that the page aspect ratio 
exactly matches that of the output area). 

Other queue processors may define their own requirements for this parameter. 

For other DC types (or default) this parameter can be NTJLL or omitted. 
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Introduction to Transforms and Matrices 


Transform matrices provide a convenient and simple way of expressing and 
manipulating most required coordinate transformation operations including: 

rotation; 

scaling (i.e., making larger or smaller); 
translation (i.e., repositioning); 

shear (i.e., creating an oblique or italicised appearance); and 
inversion (or reflection). 

These are illustrated in Figure A3-1. 

The transformation of any point (x,y) to a new position (x',y) by any of the above 
operations can be expressed by the general equations 

x ; = ax + cy + e 
y' = bx + dy + f 

that can be represented in matrix form as: 

"a b 0" 
c d 0 
_e f 1_ 

This is illustrated by the equations below (with the corresponding matrices shown 
on the right): 
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Figure A3.1 Common Transform Operations. 


Counterclockwise rotation through R degrees: 

CosR SinR 0 
-SinR CosR 0 
0 0 1 


x' = xCosR - ySinR 
y' = xSinR 4- yCosR 


(a-CosR, b-SinR, c=-SinR, d=CosR, e=0, f=0) 


Scaling x and y by scale factors of si and s2 respectively: 


x' = six 
y' = s2y 


si 0 0 

0 s2 0 

0 0 1 


(a=sl, b=0, c=0, d=s2, e~0, f=0) 
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Translation of x by tl and y by t2: 


x' = x + tl 

y' = y +12 


1 

0 

tl 


0 

1 

t2 


(a=l, b=0, c=0, d=l, e=tl, f=t2) 
Horizontal shear by an angle of S degrees from the vertical: 


x' = x + yTanS 

y' = y 


i o 

TansS 1 

0 0 


(a=l, b=0, c=TanS, d=l, e=0, f=0) 
x inversion (i.e., reflection about y axis): 


x = -x 

y # = y 


-1 

o 

o 


o 

i 

0 


(a=-l, b=0, c=0, d=l, e=0, f=0) 
y inversion (i.e., reflection about x axis): 


x = x 

y' = -y 


o 

-l 

0 


(a=l, b=0, c=0, d=-l, e=0, f=0) 


Note that inversion of both x and y is equivalent to 180 degree rotation. 
Identity: 



1 0 0 
0 1 0 
0 0 1 


(a=l, b=0, c=0, d=l, e=0, f=0) 

Matrix algebra defines the multiplication of a (1x3) and (3x3) matrix as: 


[g 


h 


s 

v 


q r 

t u 

w x 


[gp+hs+iv gq+ht+iw gr+hu+ix] 
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and multiplication of a (3x3) and (3x3) matrix as: 


g 

h 

i 


P 

q 

Y 


gp-fhs+iv 

gq+ht+iw 

gr+hu+ix 

j 

k 

1 


s 

t 

U 


jp+ks+lv 

jq+kt+lw 

jr+ku+lx 

m 

n 

0 


V 

w 

X 


mp4-ns+ov 

mq+nt+ow 

mr+nu+ox 


The equations x-ax+cy+e and y-bx+dy+f are thus expressed in matrix form as: 


[x'y'l] = [xy 1] • 


a b 0“ 

c d 0 

e f 1 


The ones and zeros in column three of these matrices exist to enable the normal 
rules of matrix algebra to be applied unchanged for coordinate transformations. 
They ensure consistency between the dimensions of input and output matrices (of 
matrix multiplications) and will, in fact, ensure that ones and zeros appear in the 
same positions of all matrices produced by matrix multiplication using such 
matrices. 

Using matrix algebra to multiply out the (1x3) and (3x3) matrix expression on 
the right above, gives a (1x3) matrix containing the required values for (x',y). That 
is: 


[xyl] • 


a b 0 
c d 0 
e f 1 


[ax+cy+e bx+dy+f 1] 


It follows that any of the above operations (rotation, scale, shear, etc.) can be 
represented by the single (3x3) matrix as shown earlier with each of the equations. 
Furthermore, any combination of such (rotation, scale, shear, etc.) matrices can be 
concatenated by matrix multiplication into a single matrix of the above form 
(although order of concatenation is important). 

The identity or unit matrix (I) shown earlier produces output values that are 
identical to its input values. The identity matrix represents the initial or reset 
value of most GPI transform matrices. 

The system frequently needs to determine the inverse of a matrix in order to 
back transform coordinates from an output to an input coordinate space. The 
inverse of a matrix A is denoted by A' 1 


If X' = X. A then X = X'. A’ 1 and A.A' 1 = I (where X' = [x' y' 1] and X = [x y 1]) 


For some matrices, it is impossible to find an inverse (e.g., a matrix that trans¬ 
forms more than one input point to a single output point). Such matrices are said 
to be singular and will cause the system to log an error (PMERR_COORDI- 
NATE_OVERFLOW). 

A word of caution is required about the use of coordinate transformation 
matrices. The equations described earlier would all produce rotation, scaling, 
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Figure A3.2 Rotation about Origin and Bottom Left of Figure. 


shear, etc., relative to the origin (0,0). If, as is likely, a figure to be transformed is 
not located at the origin and the transformation is required to be relative to a point 
on the figure such as the bottom left corner, transformation relative to the origin 
will introduce an undesired translation. This is illustrated (for rotation) in Figure 
A3-2. The simplest remedy for this is to (1) provide a matrix to translate the figure 
such that its bottom left corner (say) is at the origin; (2) provide a second matrix 
to perform the required operation (e.g., rotation); and (3) provide a third matrix to 
translate the figure back to its required position. For example, for rotation this 
might appear as follows: 


[x ; y' 1] = [x y 1] 


1 

0 

0 


CosR 

SinR 

0 


1 

0 

0 - 

0 

1 

0 


-SinR 

CosR 

0 


0 

1 

0 

-e 

-f 

1 


0 

0 

1J 


e 

f 

1 


(Where (e,f) are the coordinates of the center of rotation, and R is the angle of 
rotation (counterclockwise) in degrees.) Clearly, it would be possible to multiply 
out the above expression to reduce the three matrices to a single matrix. However, 
this is unnecessary as the system provides options (e.g., TRANSFORM_ADD) that 
enable transforms to be incrementally updated as would be required here. The 
system can, in fact, perform all required matrix multiplications. 
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Sample MetaFile Internals 


A MetaFile consists of a series of structured fields as documented in the IBM OS/2 
Programming Reference and Mixed Document Architecture Reference. Below is 
an example of a real MetaFile in hex with the different fields identified. Following 
this is a list of examples of MetaFile escape orders reflecting functions not 
supported by the interchange architecture or resource and environment changes 
that occur during drawing. 


Begin Document 


(00) (20) (D3) 
(00) (00) 

(A8) 

(A8) 

(00) 

(00) 

(00) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(31) 

(05) (18) (03) 

(0C) 

(00) 












(06) (01) (03) 
(03) (65) (00) 

(D4) 

(03) 

(52) 











Begin Resource Group 












(00) (10) (D3) 

(A8) 

(C6) 

(00) 

(00) 

(00) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(32) 

Begin Color Attribute Table (PS Logical Color Table) 






(00) (10) (D3) 

(A8) 

(77) 

(00) 

(00) 

(00) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(34) 

Color Attribute Table (PS Logical Color Table) 







(00) (DD) (D3) 

(B0) 

(77) 

(00) 

(00) 

(00) 

(40) 

(00) 

(00) 






(OF) (01) (00) 

(01) 

(00) 

(00) 

(01) 

(08) 

(08) 

(08) 

(04) 

(00) 

(00) 

(00) 

(FF) 


(OF) (01) (00) 

(01) 

(00) 

(00) 

(02) 

(08) 

(08) 

(08) 

(04) 

(00) 

(FF) 

(00) 

(00) 


(OF) (01) (00) 

(01) 

(00) 

(00) 

(03) 

(08) 

(08) 

(08) 

(04) 

(00) 

(FF) 

(00) 

(FF) 


(OF) (01) (00) 

(01) 

(00) 

(00) 

(04) 

(08) 

(08) 

(08) 

(04) 

(00) 

(00) 

(FF) 

(00) 


(OF) (01) (00) 

(01) 

(00) 

(00) 

(05) 

(08) 

(08) 

(08) 

(04) 

(00) 

(00) 

(FF) 

(FF) 


(OF) (01) (00) 

(01) 

(00) 

(00) 

(06) 

(08) 

(08) 

(08) 

(04) 

(00) 

(FF) 

(FF) 

(00) 
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Color Attribute Table (PS Logical Color Table) (continued) 

(OF) (01) (00) (01) (00) (00) (08) (08) (08) (08) (04) (00) (20) (20) (20) 

(OF) (01) (00) (01) (00) (00) (09) (08) (08) (08) (04) (00) (00) (00) (80) 

(OF) (01) (00) (01) (00) (00) (0A) (08) (08) (08) (04) (00) (80) (00) (00) 

(OF) (01) (00) (01) (00) (00) (0B) (08) (08) (08) (04) (00) (80) (00) (80) 

(OF) (01) (00) (01) (00) (00) (OC) (08) (08) (08) (04) (00) (00) (80) (00) 

(OF) (01) (00) (01) (00) (00) (OD) (08) (08) (08) (04) (00) (00) (80) (80) 

(OF) (01) (00) (01) (00) (00) (OE) (08) (08) (08) (04) (00) (80) (80) (00) 

(OF) (01) (00) (01) (00) (00) (OF) (08) (08) (08) (04) (00) (80) (80) (80) 


End Color Attribute Table (PS Logical Color Table) 

(00) (10) (D3) (A9) (77) (00) (00) (00) (30) (30) (30) (30) (30) (30) (30) (34) 

Begin Image Object (Bitmap 1) - Image Name: 3E 34 33 3C 30 30 30 34 (Hex) 

(00) (10) (D3) (A8) (FB) (00) (00) (00) (3E) (34) (33) (3C) (30) (30) (30) (34) 


Begin Resource Group (Bitmap 1 Color Table) 

(00) (10) (D3) (A8) (C6) (00) (00) (00) (30) (34) (30) (30) (33) (3C) (3E) (34) 


Begin Color Attribute Table (Bitmap 1 Color Table) 

(00) (10) (D3) (A8) (77) (00) (00) (00) (30) (34) (30) (30) (33) (3C) (3E) (34) 


Color Attribute Table (Bitmap 1 Color Table) 

(00) (1C) (D3) (B0) (77) (00) (00) (00) (00) (00) (01) 

(11) (01) (00) (01) (00) (00) (00) (08) (08) (08) (03) (00) (00) (00) (FF) (FF) 

(FF) 

End Color Attribute Table (Bitmap 1 Color Table) 

(00) (10) (D3) (A9) (77) (00) (00) (00) (30) (34) (30) (30) (33) (3C) (3E) (34) 

End Resource Group (Bitmap 1 Color Table) 

(00) (10) (D3) (A9) (C6) (00) (00) (00) (30) (34) (30) (30) (33) (3C) (3E) (34) 

Begin Object Environment Group (Bitmap 1 Color Table) 

(00) (10) (D3) (A8) (C7) (00) (00) (00) (3E) (34) (33) (3C) (30) (30) (30) (34) 

Map Color Attribute Table (Bitmap 1 Color Table) 

(00) (1A) (D3) (AB) (77) (00) (00) (00) (00) (12) 

(0C) (02) (84) (00) (30) (34) (30) (30) (33) (3C) (3E) (34) 

(04) (24) (07) (01) 


End Object Environment Group (Bitmap 1 Color Table) 


(00) (10) (D3) (A9) (C7) (00) (00) (00) (3E) (34) (33) (3C) (30) (30) (30) (34) 
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Image Data Descriptor (Bitmap 1 Data) 


(00) (11) (D3) (A6) (FB) (00) (00) (00) (01) (00) (C8) (01) (0A) (00) (0A) (00) 
(0A) 


Image Picture Data (Bitmap 1 Data) 


(00) (22) (D3) (EE) (FB) (00) (00) (00) 

(70) (00) 

(91) (01) (FF) 

(94) (09) (02) (00) (00) (00) (00) (00) (0A) (00) (OA) 

(95) (02) (03) (03) 

(96) (01) (01) 

(97) (01) (01) 


Image Picture Data (Bitmap 1 Data) 

(00) (38) (D3) (EE) (FB) (00) (00) (00) 

(FE) (92) (00) (28) (FF) (CO) (00) (00) (9E) (7A) (DE) (CO) (9E) (40) (OA) (02) 

(CO) (Cl) (00) (00) (CC) (CO) (02) (00) (ED) (CO) (00) (80) (El) (Cl) (00) (00) 

(F3) (CO) (80) (02) (F3) (CO) (00) (00) (FF) (CO) (03) (00) (93) (00) (71) (00) 


End Image Object (Bitmap 1) 


(00) (10) (D3) (A9) (FB) (00) (00) (00) (3E) (34) (33) (3C) (30) (30) (30) (34) 


Begin Image Object (Bitmap 2) - Image Name: 38 34 22 3C 30 30 30 34 (Hex) _ 

(00) (10) (D3) (A8) (FB) (00) (00) (00) (38) (34) (33) (3C) (30) (30) (30) (34) 


Begin Resource Group (Bitmap 2 Color Table) 

(00) (10) (D3) (A8) (C6) (00) (00) (00) (30) (34) (30) (30) (33) (3C) (38) (34) 


Begin Color Attribute Table (Bitmap 2 Color Table) 

(00) (10) (D3) (A8) (77) (00) (00) (00) (30) (34) (30) (30) (33) (3C) (38) (34) 


Color Attribute Table (Bitmap 2 Color Table) 

(00) (1C) (D3) (B0) (77) (00) (00) (00) (00) (00) (01) 

(11) (01) (00) (01) (00) (00) (00) (08) (08) (08) (03) (00) (00) (00) (FF) (FF) 

(FF) 


End Color Attribute Table (Bitmap 2 Color Table) 

(00) (10) (D3) (A9) (77) (00) (00) (00) (30) (34) (30) (30) (33) (3C) (38) (34) 


End Resource Group (Bitmap 2 Color Table) 

(00) (10) (D3) (A9) (C6) (00) (00) (00) (30) (34) (30) (30) (33) (3C) (38) (34) 
Begin Object Environment Group (Bitmap 2 MCA) 


(00) (10) (D3) (A8) (C7) (00) (00) (00) (38) (34) (33) (3C) (30) (30) (30) (34) 
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Map Color Attribute Table (Bitmap 2 MCA) 

(00) (1A) (D3) (AB) (77) (00) (00) (00) (00) (12) 

(0C) (02) (84) (00) (30) (34) (30) (30) (33) (3C) (38) (34) 
(04) (24) (07) (01) 


End Object Environment Group (Bitmap 2 MCA) 

(00) (10) (D3) (A9) (C7) (00) (00) (00) (38) (34) (33) (3C) (30) (30) (30) (34) 

Image Data Descriptor (Bitmap 2 Data) 

(00) (11) (D3) (A6) (FB) (00) (00) (00) (01) (00) (C8) (01) (0A) (00) (0A) (00) 

(0A) 

Image Picture Data (Bitmap 2 Data) 

(00) (22) (D3) (EE) (FB) (00) (00) (00) 

(70) (00) 

(91) (01) (FF) 

(94) (09) (02) (00) (00) (00) (00) (00) (0A) (00) (0A) 

(95) (02) (03) (03) 

(96) (01) (01) 

(97) (01) (01) 


Image Picture Data (Bitmap 2 Data) 

(00) (38) (D3) (EE) (FB) (00) (00) (00) 

(FE) (92) (00) (28) (FF) (CO) (00) (00) (9F) (06) (8E) (01) (CE) (46) (3F) (01) 

(E4) (Cl) (20) (01) (FI) (CO) (02) (00) (FI) (Cl) (00) (80) (E4) (Cl) (00) (00) 

(CE) (41) (84) (01) (9F) (00) (60) (01) (FF) (CO) (03) (00) (93) (00) (71) (00) 


End Image Object (Bitmap 2 Data) 


(00) (10) (D3) (A9) (FB) (00) 

Begin Graphics Object 

(00) 

(00) 

(38) 

(34) 

(33) 

(3C) 

(30) 

(30) 

(30) 

(34) 

(00) (10) (D3) (A8) (BB) (00) 

(00) 

(00) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(37) 

Begin Object Environment Group 










(00) (10) (D3) (A8) (C7) (00) 

(00) 

(00) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(37) 

Map Color Attribute Table 











(00) (16) (D3) (AB) (77) (00) 

(00) 

(00) 

(00) 

(0E) 







(0C) (02) (84) (00) (30) (30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(34) 





Map Coded Font (Default Font Lcid = 0) 









(00) (20) (D3) (AB) (8A) (00) 

(00) 

(00) 

(00) 

(18) 







(0C) (02) (84) (00) (FF) (00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 






(04) (24) (05) (00) 

(06) (20) (03) (D4) (03) (52) 
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Map Coded Font (Logical Font Lcid = 1) 

(00) (58) (D3) (AB) (8A) (00) (00) (00) (00) (50) 

(0C) (02) (84) (00) (46) (4F) (4E) (54) (30) (31) (00) (43) 

(04) (24) (05) (01) 

(14) (IF) (05) (05) (00) (OF) (00) (0C) (00) (00) (00) (00) (00) (00) (00) (00) 

( 00 ) ( 00 ) ( 00 ) ( 00 ) 

(06) (20) (03) (D4) (03) (52) 

(24) (02) (08) (00) (43) (6F) (75) (72) (69) (65) (72) (00) (53) (01) (43) (00) 

(E8) (3F) (55) (01) (1A) (01) (00) (00) (00) (00) (40) (3F) (E8) (3F) (8F) (05) 

(IE) (2E) (51) (55) 

Map Coded Font (Logical Font Lcid = 2) 

(00) (58) (D3) (AB) (8A) (00) (00) (00) (00) (50) 

(0C) (02) (84) (00) (46) (4F) (4E) (54) (30) (31) (00) (46) 

(04) (24) (05) (02) 

(14) (IF) (05) (05) (00) (0C) (00) (09) (00) (00) (00) (00) (00) (00) (00) (00) 

( 00 ) ( 00 ) ( 00 ) ( 00 ) 

(06) (20) (03) (D4) (03) (52) 

(24) (02) (08) (00) (43) (6F) (75) (72) (69) (65) (72) (00) (53) (01) (43) (00) 

(E8) (3F) (55) (01) (1A) (01) (00) (00) (00) (00) (40) (3F) (E8) (3F) (8F) (05) 

(IE) (2E) (51) (55) 

Map Data Resource (Bitmap 1) - Image Name: 3E 34 33 3C 30 30 30 34 (Hex) 
Bitmap Handle: 0x04003CE4 

(00) (ID) (D3) (AB) (C3) (00) (00) (00) (00) (15) 

(0C) (02) (84) (00) (3E) (34) (33) (3C) (30) (30) (30) (34) 

(07) (22) (10) (04) (00) (3C) (E4) 

Map Data Resource (Bitmap 2) - Image Name: 38 34 22 3C 30 30 30 34 (Hex) _ 

Bitmap Handle: 0x04003C84 

(00) (ID) (D3) (AB) (C3) (00) (00) (00) (00) (15) 

(0C) (02) (84) (00) (38) (34) (33) (3C) (30) (30) (30) (34) 

(07) (22) (10) (04) (00) (3C) (84) 

End Object Environment Group 

(00) (10) (D3) (A9) (C7) (00) (00) (00) (30) (30) (30) (30) (30) (30) (30) (37) 

Graphics Data Descriptor (GDD) 

(00) (8B) (D3) (A6) (BB) (00) (00) (00) 

Specify GVM subset (GDD) 

(F7) (07) (B0) (00) (00) (23) (01) (01) (05) 

Set Picture Descriptor (GDD - PS Page Units, etc.) 

(F6) (28) (60) (00) (05) (00) (01) (00) (00) (00) (01) (00) (00) (00) (00) (00) 

(00) (00) (00) (00) (00) (00) (80) (02) (00) (00) (00) (00) (00) (00) (5E) (01) 
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Set Picture Descriptor (GDD - PS Page Units, etc.) (continued) 

( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) 

Set Current Defaults (GDD) 

Set Default Parameter Format - GPIF_SHORT/GPIFJLONG PS coordinate 
format 

(21) (07) (08) (EG) (00) (8F) (00) (05) (05) 

Set Current Defaults (GDD) Set Default Viewing Transform 

(21) (1C) (07) (CC) (0C) (8F) (00) (00) (02) (00) (00) (00) (00) (00) (00) (00) 

(00) (00) (00) (00) (02) (00) (14) (00) (00) (00) (14) (00) (00) (00) 

Set Current Defaults (GDD) Set Default Character Attributes 

(21) (10) (02) (40) (00) (8F) (09) (00) (00) (00) (0C) (00) (00) (00) (00) (00) 

( 00 ) ( 00 ) 

Set Current Defaults (GDD) Set Default Marker Attributes 

(21) (0C) (03) (40) (00) (8F) (09) (00) (00) (00) (09) (00) (00) (00) 

Set Bitmap Identifier - handles 84 3C 00 04 (hex) Lcids 04 (hex) 

(E7) (07) (80) (00) (84) (3C) (00) (04) (04) 

Graphics Data 

(00) (66) (D3) (EE) (BB) (00) (00) (00) 

Begin Segment (Segment ID = OxOOOOOOOA- unchained called segment) 

(70) (OF) (00) (00) (00) (0A) (50) (80) (00) (4E) (00) (00) (00) (00) (00) (00) 

Set Indexed Color (GSICOL) 

(A6) (04) (00) (04) (00) (00) 

Set Current Position (GSCP) 

(21) (08) (0A) (00) (00) (00) (OF) (00) (00) (00) 

Line at Current Position (GCLINE) 

(81) (08) (32) (00) (00) (00) (OF) (00) (00) (00) 

Set Pattern Set (GSPS) 

(08) (04) 

Set Indexed Color (GSICOL) 


(A6) (04) (00) (02) (00) (00) 
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Begin Area (GEAR) 

(68) (AO) 

Set Current Position (GSCP) 

(21) (08) (32) (00) (00) (00) (32) (00) (00) (00) 

Line at Current Position (GCLINE) 

(81) (08) (96) (00) (00) (00) (96) (00) (00) (00) 

Line at Current Position (GCLINE) 

(81) (08) (2C) (01) (00) (00) (32) (00) (00) (00) 

Line at Current Position (GCLINE) 

(81) (08) (32) (00) (00) (00) (32) (00) (00) (00) 

End Area (GEAR) 

(60) (00) 

Graphics Data 

(01) (66) (D3) (EE) (BB) (00) (00) (00) 

GDF Begin Segment Order (Segment ID = 0) 

(70) (0E) (00) (00) (00) (00) (70) (00) (00) (16) (00) (00) (00) (00) (00) (00) 

Extended Escape (MetaFile Escape Order - GpiSetGraphicsField 0x0A00) 

(FE)(D5) (00) (12) (00) (0A) (00) (00) (00) (00) (00) (00) (00) (00) (90) (01) 

(00) (00) (90) (01) (00) (00) 

GDF Begin Segment Order (ID = 0x00000014 - chained segment) 

(70) (0E) (00) (00) (00) (14) (50) (00) (00) (2E) (00) (00) (00) (00) (00) (00) 

Bitbit (GBBLT) ___ 

(D6) (2C) (00) (00) (CC) (00) (E4) (3C) (00) (04) (00) (01) (01) (00) (00) (00) 

(00) (00) (64) (00) (00) (00) (0A) (00) (00) (00) (6E) (00) (00) (00) (00) (00) 

(00) (00) (00) (00) (00) (00) (0A) (00) (00) (00) (0A) (00) (00) (00) 

Begin Segment (ID = OxOOQOOOXE - chained segment with prolog) 

(70) (0E) (00) (00) (00) (IE) (50) (10) (00) (9C) (00) (00) (00) (00) (00) (00) 

Set Viewing Transform (GSTV) 

(31) (1C) (00) (00) (CC) (0C) (00) (00) (02) (00) (00) (00) (00) (00) (00) (00) 

(00) (00) (00) (00) (02) (00) (00) (00) (00) (00) (00) (00) (00) (00) 
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Push and Set Model Transform (GPSTM) 

(64) (1C) (00) (01) (CC) (0C) (00) (00) (01) (00) (00) (00) (00) (00) (00) (00) 

( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 01 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) 

End Prologue (GEPROL) 

(3E) (00) __ 

Begin Element (GBEL - Call Segment) 

(D2) (04) (07) (00) (00) (00) _ 

Push and Set Model Transform (GPSTM - Call Segment) 

(64) (1C) (00) (01) (CC) (0C) (00) (00) (01) (00) (00) (00) (00) (00) (00) (00) 

( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 01 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) 

Call Segment (GCALLS - Call Segment) 

(07) (06) (00) (00) (0A) (00) (00) (00) 

Pop (GPOP - Call Segment) 

(3F) (00) __ 

End Element (GEEL - CA11 Segment) 

(49) (00) 

End Image (GEIMG) 

(93) (00) ~~ 

Set Indexed Color (GSICOL) 

(A6) (04) (00) (02) (00) (00) ” . . 

Set Current Position (GSCP) 

(21) (08) (0A) (00) (00) (00) (14) (00) (00) (00) ~~ 

Line at Current Position (GCLINE) 

(81) (08) (0A) (00) (00) (00) (28) (00) (00) (00) — 

Set Character Set (GSCS) 

(38) (01) ‘ — « — 

Character String Move at Current Position (GCCHSTM) 

(Bl) (06) (41) (42) (43) (44) (45) (46) 

Set Character Set (GSCS) 


(38) (02) 
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Character String Move at Current Position (GCCHSTM) 


(Bl) (06) (47) (48) (49) (4A) (4B) 

GDF Begin Segment Order (ID - 0 

(4C) 

- null segment zero with prolog) 



(70) (0E) (00) (00) (00) (00) (71) 

Set Viewing Transform (GSTV) 

(10) 

(00) 

(3E) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(31) (1C) (00) (00) (CC) (0C) 

(00) 

(00) 

(01) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) (00) (00) (00) (01) (00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 



Push and Set Model Transform (GPSTM) 








(64) (1C) (00) (01) (CC) (0C) 

(00) 

(00) 

(01) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) (00) (00) (00) (01) (00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 



End Prologue (GEPROL) 











(3E) (00) 











End Graphics Object 











(00) (10) (D3) (A9) (BB) (00) 

(00) 

(00) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(37) 

End Resource Group 











(00) (10) (D3) (A9) (C6) (00) 

(00) 

(00) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(32) 

End Document 











(00) (10) (D3) (A9) (A8) (00) 

(00) 

(00) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(30) 

(31) 

Examples of MetaFile escape orders: 







Long Escape (GpiSetPel 0x01) 










(D5)(0A) (80) (01) (32) (00) 

(00) 

(00) 

(32) 

(00) 

(00) 

(00) 





Long Escape (GpiBitBlt 0x02) 











(D5) (32) (80) (02) (00) (CC) 

(00) 

(04) 

(F0) 

(2B) 

(00) 

(04) 

(00) 

(00) 

(00) 

(00) 

(00) (00) (00) (00) (00) (00) 

(00) 

(00) 

(64) 

(00) 

(00) 

(00) 

(0A) 

(00) 

(00) 

(00) 

(6E) (00) (00) (00) (00) (00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(0A) 

(00) 

(00) 

(00) 

(0A) (00) (00) (00) 











Extended Escape (GpiCreateLogColorTable 0x01000) 






(FE)(D5) (00) (52) (00) (01) 

(01) 

(00) 

(00) 

(00) 

(02) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) (00) (10) (00) (00) (00) 

(00) 

(00) 

(00) 

(00) 

(80) 

(00) 

(00) 

(00) 

(00) 

(80) 

(00) (00) (80) (80) (00) (00) 

(00) 

(00) 

(80) 

(00) 

(80) 

(00) 

(80) 

(00) 

(00) 

(80) 

(80) (00) (80) (80) (80) (00) 

(20) 

(20) 

(20) 

(00) 

(FF) 

(00) 

(00) 

(00) 

(00) 

(FF) 

(00) (00) (FF) (FF) (00) (00) 

(00) 

(00) 

(FF) 

(00) 

(FF) 

(00) 

(FF) 

(00) 

(00) 

(FF) 


(FF) (00) (FF) (FF) (FF) (00) 
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Extended Escape (GpiCreateLogFont 0x0200) 

(FE)(D5) (00) (46) (00) (02) (46) (4F) (4E) (54) (30) (31) (00) (00) (01) (00) 

(00) (00) (38) (00) (00) (00) (00) (00) (00) (00) (43) (6F) (75) (72) (69) (65) 

(72) (00) (67) (01) (00) (00) (00) (00) (CA) (2C) (CE) (2C) (4E) (71) (50) (5A) 

(67) (01) (87) (00) (19) (13) (E8) (2C) (C6) (46) (00) (00) (B5) (01) (08) (00) 

(00) (00) (06) (00) (00) (00) (00) (00) (00) (00) 


Extended Escape (GpiDeleteSetld 0x0300) 

(FE)(D5) (00) (06) (00) (03) (01) (00) (00) (00) 

Extended Escape (GpiResetPS 0x0500) 

(FE)(D5) (00) (06) (00) (05) (04) (00) (00) (00) 

Extended Escape (GpiSetDrawControl - DCTLJDXSPLAY 0x0600) 

(FE)(D5) (00) (06) (00) (06) (00) (00) (00) (00) 

Extended Escape (GpiSetBitmapXd 0x0700) 

(FE)(D5) (00) (0A) (00) (07) (24) (3A) (00) (04) (16) (00) (00) (00) 

Extended Escape (GpiSetCp 0x0800) 

(FE)(D5) (00) (06) (00) (08) (B5) (01) (00) (00) 

Extended Escape (GpiSetDefaultViewMatrix 0x0900) 

(FE)(D5) (00) (IE) (00) (09) (00) (00) (02) (00) (00) (00) (00) (00) (00) (00) 

(00) (00) (00) (00) (02) (00) (14) (00) (00) (00) (14) (00) (00) (00) (00) (00) 

( 00 ) ( 00 ) 


Extended Escape (GpiSetGraphicsField OxOAOO) 

(FE)(D5) (00) (12) (00) (0A) (0A) (00) (00) (00) (OA) (00) (00) (00) (E8) (03) 
(00) (00) (E8) (03) (00) (00) 


Extended Escape (GpiErase OxOCOO) 
(FE)(D5) (00) (02) (00) (OC) 


Extended Escape (GpiXntersectClipRectangle OxQDOO) 

(FE)(D5) (00) (12) (00) (OD) (OA) (00) (00) (00) (OA) (00) (00) (00) (E8) (03) 
(00) (00) (E8) (03) (00) (00) 


Extended Escape (GpiOffsetClipRegion OxOEOO) 

(FE)(D5) (00) (12) (00) (OE) (64) (00) (00) (00) (96) (00) (00) (00) (00) (00) 

( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) 


Extended Escape (GpiExcludeCIipRectangle OxOFOO) 

(FE)(D5) (00) (12) (00) (OF) (OA) (00) (00) (00) (OA) (00) (00) (00) (E8) (03) 
(00) (00) (E8) (03) (00) (00) 
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Extended Escape (GpiSetClipRegion 0x1000) 

(FE)(D5) (00) (36) (00) (10) (03) (00) (00) (00) (64) (00) (00) (00) (DC) (00) 

(00) (00) (78) (00) (00) (00) (90) (01) (00) (00) (0A) (00) (00) (00) (C8) (00) 

(00) (00) (90) (01) (00) (00) (DC) (00) (00) (00) (64) (00) (00) (00) (0A) (00) 

(00) (00) (78) (00) (00) (00) (C8) (00) (00) (00) 


Extended Escape (GpiSetClipRegion - NULL 0x1100) 
(FE)(D5) (00) (06) (00) (11) (00) (00) (00) (00) 


Extended Escape (GpiPaintRegion 0x1200) 


(FE)(D5) (00) (36) 
(00) (00) (78) (00) 
(00) (00) (90) (01) 
(00) (00) (78) (00) 


(00) (12) (03) (00) 
(00) (00) (90) (01) 
(00) (00) (DC) (00) 
(00) (00) (C8) (00) 


(00) (00) (64) (00) 
(00) (00) (0A) (00) 
(00) (00) (64) (00) 
( 00 ) ( 00 ) 


(00) (00) (DC) (00) 
(00) (00) (C8) (00) 
(00) (00) (0A) (00) 


Extended Escape (DevEscape code=0x3FAD 0x1300) 

(FE)(D5) (00) (0C) (00) (13) (AD) (3F) (00) (00) (02) (00) (00) (00) (01) (00) 


Extended Escape (GpiSavePS 0x1400) 
(FE)(D5) (00) (02) (00) (14) 


Extended Escape (GpiRestorePS 0x1500) 

(FE) (D5) (00) (06) (00) (15) (01) (00) (00) (00) 


Extended Escape (GpiSetDefAttrs 0x1600) 

(FE) (D5) (00) (24) (00) (16) (01) (00) (00) (00) (F5) (01) (00) (00) (01) (00) 

(00) (00) (11) (00) (00) (00) (02) (00) (87) (00) (00) (00) (01) (00) (01) (00) 

(00) (00) (07) (00) (01) (00) (01) (00) 


Extended Escape (GpiSetDefTag 0x1700) 

(FE) (D5) (00) (06) (00) (17) (02) (00) (00) (00) 


Extended Escape (GpiSetDefViewingLimits 0x1800) 

(FE) (D5) (00) (12) (00) (18) (0A) (00) (00) (00) (0A) (00) (00) (00) (E8) (03) 
(00) (00) (E8) (03) (00) (00) 


Extended Escape (GpiSetDefArcParams 0x1900) 

(FE) (D5) (00) (12) (00) (19) (02) (00) (00) (00) (02) (00) (00) (00) (00) (00) 

( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) 



APPENDIX 5 


Sample Orders 


Below are sample orders that may be found in MetaFiles or used with and 
returned by GpiPutBata, GpiGetData, GpiElement, and G-piQueryElement. The 
"short format” orders apply to a PS created using the GPIF__SHORT GpiCreatePS 
option. The "push and set” versions of the orders are generated if the attribute 
mode for the PS is set to AM_PRESERVE. The long and short format versions of 
a particular order are not, in all cases, equivalent. 

Arc at Given Position (GARC) 

(C6) (18) (50) (00) (00) (00) (50) (00) (00) (00) (32) (00) (00) (00) (32) (00) 

(00) (00) (64) (00) (00) (00) (32) (00) (00) (00) 

Arc at Given Position (GCARC - short format) 

(C6) (0C) (50) (00) (50) (00) ((32) (00) (32) (00) (64) (00) (32) (00) 

Arc at Current Position (GCARC) 

(86) (10) (32) (00) (00) (00) (32) (00) (00) (00) (64) (00) (00) (00) (32) (00) 

( 00 ) ( 00 ) 

Arc at Current Position (GCARC - short format) 

(86) (08) (32) (00) (32) (00) (64) (00) (32) (00) 

Begin Area (GEAR) 

(68) (A0) ~ 

Begin Element (GBEL - Call Segment) 

(D2) (04) (07) (00) (00) (00) 
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(D1)(0E) (50) (00) (00) (00) (50) (00) (00) (00) (00) (00) (00) (20) (00) (38) 


Begin Image at Given Position (GCBIMG - short format) 


(D1)(0A) (50) 

(00) 

(50) 

(00) 

(00) 

(00) 

(00) 

(20) 

(00) 

(38) 





Begin Image at Current Position (GCBIMG) 








(91) (06) (00) 

(00) 

(00) 

(20) 

(00) 

(38) 









Begin Path 














(B0) (06) (00) 

(00) 

(01) 

(00) 

(00) 

(00) 









Bezier Curve at Given Position (GBEZ) 









(E5) (80) (50) 

(00) 

(00) 

(00) 

(50) 

(00) 

(00) 

(00) 

(4B) 

(00) 

(00) 

(00) 

(2C) 

(01) 

(00) (00) (64) 

(00) 

(00) 

(00) 

(96) 

(00) 

(00) 

(00) 

(7D) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) (00) (96) 

(00) 

(00) 

(00) 

(96) 

(00) 

(00) 

(00) 

(AF) 

(00) 

(00) 

(00) 

(2C) 

(01) 

(00) (00) (C8) 

(00) 

(00) 

(00) 

(96) 

(00) 

(00) 

(00) 

(El) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) (00) (FA) 

(00) 

(00) 

(00) 

(96) 

(00) 

(00) 

(00) 

(13) 

(01) 

(00) 

(00) 

(2C) 

(01) 

(00) (00) (2C) 

(01) 

(00) 

(00) 

(96) 

(00) 

(00) 

(00) 

(45) 

(01) 

(00) 

(00) 

(00) 

(00) 

(00) (00) (5E) 

(01) 

(00) 

(00) 

(9B) 

(00) 

(00) 

(00) 

(77) 

(01) 

(00) 

(00) 

(2C) 

(01) 

(00) (00) (90) 

(01) 

(00) 

(00) 

(96) 

(00) 

(00) 

(00) 

(A9) 

(01) 

(00) 

(00) 

(00) 

(00) 

(00) (00) 














Bezier Curve at Given Position (GBEZ - 

short format) 






(E5) (40) (50) 

(00) 

(50) 

(00) 

(4B) 

(00) 

(2C) 

(01) 

(64) 

(00) 

(96) 

(00) 

(7D) 

(00) 

(00) (00) (96) 

(00) 

(96) 

(00) 

(AF) 

(00) 

(2C) 

(01) 

(C8) 

(00) 

(96) 

(00) 

(El) 

(00) 

(00) (00) (FA) 

(00) 

(96) 

(00) 

(13) 

(01) 

(2C) 

(01) 

(2C) 

(01) 

(96) 

(00) 

(45) 

(01) 

(00) (00) (5E) 

(01) 

(9B) 

(00) 

(77) 

(01) 

(2C) 

(01) 

(90) 

(01) 

(96) 

(00) 

(A9) 

(01) 

(00) (00) 














Bezier Curve at Current Position (GCBEZ) 








(A5) (78) (4B) 

(00) 

(00) 

(00) 

(2C) 

(01) 

(00) 

(00) 

(64) 

(00) 

(00) 

(00) 

(96) 

(00) 

(00) (00) (7D) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(96) 

(00) 

(00) 

(00) 

(96) 

(00) 

(00) (00) (AF) 

(00) 

(00) 

(00) 

(2C) 

(01) 

(00) 

(00) 

(C8) 

(00) 

(00) 

(00) 

(96) 

(00) 

(00) (00) (El) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(FA) 

(00) 

(00) 

(00) 

(96) 

(00) 

(00) (00) (13) 

(01) 

(00) 

(00) 

(20 

(01) 

(00) 

(00) 

(2C) 

(01) 

(00) 

(00) 

(96) 

(00) 

(00) (00) (45) 

(01) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(5E) 

(01) 

(00) 

(00) 

(9B) 

(00) 

(00) (00) (77) 

(01) 

(00) 

(00) 

(20 

(01) 

(00) 

(00) 

(90) 

(01) 

(00) 

(00) 

(96) 

(00) 

(00) (00) (A9) 

(01) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 







Bezier Curve at Current Position (GCBEZ - short format) 





(A5) (3C) (4B) 

(00) 

(2C) 

(01) 

(64) 

(00) 

(96) 

(00) 

(7D) 

(00) 

(00) 

(00) 

(96) 

(00) 

(96) (00) (AF) 

(00) 

(2C) 

(01) 

(C8) 

(00) 

(96) 

(00) 

(El) 

(00) 

(00) 

(00) 

(FA) 

(00) 

(96) (00) (13) 

(01) 

(2C) 

(01) 

(20 

(01) 

(96) 

(00) 

(45) 

(01) 

(00) 

(00) 

(5E) 

(01) 

(9B) (00) (77) 

(01) 

(2C) 

(01) 

(90) 

(01) 

(96) 

(00) 

(A9) 

(01) 

(00) 

(00) 
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Bitblt (GBBLT) 


(D6)(2C) (00) (00) (CC) (00) (E4) 

(3C) 

(00) 

(04) 

(00) 

(01) 

(01) 

(00) 

(00) 

(00) 

(00) (00) (64) (00) (00) (00) (0A) 

(00) 

(00) 

(00) 

(6E) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) (00) (00) (00) (00) (00) (OA) 

(00) 

(00) 

(00) 

(0A) 

(00) 

(00) 

(00) 



Bitblt (GBBLT - short format) 










(D6) (24) (00) (00) (CC) (00) (50) 

(2C) 

(00) 

(04) 

(00) 

(01) 

(01) 

(00) 

(00) 

(00) 

(64) (00) (OA) (00) (6E) (00) (00) 
(00) (00) (OA) (00) (00) (00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(0A) 

(00) 

Box at Given Position (GBOX) 










(C0) (1A) (40) (00) (50) (00) (00) 

(00) 

(50) 

(00) 

(00) 

(00) 

(20) 

(00) 

(00) 

(00) 

(20) (00) (00) (00) (00) (00) (00) 

(00) 

(00) 

(00) 

(00) 

(00) 





Box at Given Position (GBOX - short format) 








(C0) (0E) (40) (00) (50) (00) (50) 

(00) 

(20) 

(00) 

(20) 

(00) 

(00) 

(00) 

(00) 

(00) 

Box at Current Position (GCBOX) 










(80) (12) (40) (00) (20) (00) (00) 
(00) (00) (00) (00) 

(00) 

(20) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

(00) 

Box at Current Position (GCBOX - 

short format) 







(80) (0A) (40) (00) (20) (00) (20) 

(00) 

(00) 

(00) 

(00) 

(00) 





Call Segment (GCALLS) 










(07) (06) (00) (00) (0A) (00) (00) 

(00) 









Character String at Given Position (GCHST) 








(C3) (17) (64) (00) (00) (00) (64) 

(00) 

(00) 

(00) 

(47) 

(70) 

(69) 

(43) 

(68) 

(61) 

(72) (53) (74) (72) (69) (6E) (67) 

(41) 

(74) 








Character String at Given Position (GCHST - 

short format) 





(C3) (13) (64) (00) (64) (00) (47) 
(69) (6E) (67) (41) (74) 

(70) 

(69) 

(43) 

(68) 

(61) 

(72) 

(53) 

(74) 

(72) 

Character String at Current Position (GCCHST) 







(83) (OF) (47) (70) (69) (43) (68) 
(74) 

(61) 

(72) 

(53) 

(74) 

(72) 

(69) 

(6E) 

(67) 

(41) 

Character String Extended at Given Position (GCHSTE) 





(FE)(F0) (GO) (76) (64) (00) (00) 

(00) 

(64) 

(00) 

(00) 

(00) 

(DO) 

(00) 

(64) 

(00) 

(00) (00) (5A) (00) (00) (00) (AE) 

(01) 

(00) 

(00) 

(78) 

(00) 

(00) 

(00) 

(00) 

(12) 

(47) (70) (69) (43) (68) (61) (72) 

(53) 

(74) 

(72) 

(69) 

(6E) 

(67) 

(50) 

(6F) 

(73) 

(41) (74) (14) (00) (00) (00) (14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) (00) (14) (00) (00) (00) (14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 
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Character String Extended at Given Position (GCHSTE) (continued) 


(00) (00) (14) (00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) (00) (14) (00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) (00) (14) (00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 







Character String Extended at Given Position (GCHSTE 

- short format) 



(FE)(F0) (00) (46) 

(64) 

(00) 

(64) 

(00) (DO) 

(00) 

(64) 

(00) 

(5A) 

(00) (AE) 

(01) 

(78) (00) (00) (12) 

(47) 

(70) 

(69) 

(43) 

(68) 

(61) 

(72) 

(53) 

(74) 

(72) 

(69) 

(6E) 

(67) (50) (6F) (73) 

(41) 

(74) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) (00) (14) (00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) (00) (14) (00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 







Character String Extended at Current Position (GCCHSTE) 





(EE) (B0) (00) (64) 

(DO) 

(00) 

(64) 

(00) 

(00) 

(00) 

(5A) 

(00) 

(00) 

(00) 

(72) 

(01) 

(00) (00) (78) (00) 

(00) 

(00) 

(00) 

(10) 

(47) 

(70) 

(69) 

(43) 

(68) 

(61) 

(72) 

(53) 

(74) (72) (69) (6E) 

(67) 

(50) 

(6F) 

(73) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) (00) (00) (00) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) (00) (00) (00) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) (00) (00) (00) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) 

(00) 

(00) 

(00) 

(14) (00) (00) (00) 

(14) 

(00) 

(00) 

(00) 









Character String Extended at Given Position (GCCHSTE - short format) 


(FE) (B0) (00) (3C) 

(DO) 

(00) 

(64) 

(00) 

(5A) 

(00) 

(72) 

(01) 

(78) 

(00) 

(00) 

(10) 

(47) (70) (69) (43) 

(68) 

(61) 

(72) 

(53) 

(74) 

(72) 

(69) 

(6E) 

(67) 

(50) 

(6F) 

(73) 

(14) (00) (14) (00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) (00) (14) (00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

(14) 

(00) 

Character String Move at Given Position (GCHSTM) 






(Fl) (17) (64) (00) 

(00) 

(00) 

(64) 

(00) 

(00) 

(00) 

(47) 

(70) 

(69) 

(43) 

(68) 

(61) 

(72) (53) (74) (72) 

(69) 

(6E) 

(67) 

(41) 

(74) 








Character String Move at Given Position (GCHSTM - short format) 



(Fl) (13) (64) (00) 

(64) 

(00) 

(47) 

(70) 

(69) 

(43) 

(68) 

(61) 

(72) 

(53) 

(74) 

(72) 

(69) (6E) (67) (41) 

(74) 












Character String Move at Current Position (GCCHSTM) 





(Bl) (0D) (47) (70) 

(69) 

(43) 

(68) 

(61) 

(72) 

(53) 

(74) 

(72) 

(69) 

(6E) 

(67) 


Close Figure (GCLFIG) 












(7D) (00) 













Comment (GCOMT) 












(01) (07) (43) (4F) 

(4D) 

(4D) 

(45) 

(4E) 

(54) 








End Area (GEAR) 














(60) (00) 
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End Element (GEEL) 
(49) (00) 

End Image (GEIMG) 
(93) (00) 


End of Symbol Definition (GESD) 
(FF) 

End Path 
(7F) (00) 

End Prologue (GEPRQL) _ 

(3E) (00) 


Escape (GESCP) 


(D5)(0A) (80) (01) (32) (00) (00) (00) (32) (00) (00) (00) 


Extended Escape (GEESCP) 

(FE)(D5) (00) (06) (00) (17) (02) (00) (00) (00) 

Fill Path (GFPTH) ___ 

(D7) (06) (20) (00) (01) (00) (00) (00) 


Fillet at Given Position (GFLT) 

(C5) (48) (50) (00) (00) (00) (50) (00) (00) (00) (4B) (00) (00) (00) (0E) (01) 

(00) (00) (7D) (00) (00) (00) (0A) (00) (00) (00) (AF) (00) (00) (00) (0E) (01) 

(00) (00) (El) (00) (00) (00) (0A) (00) (00) (00) (13) (01) (00) (00) (0E) (01) 

(00) (00) (45) (01) (00) (00) (0A) (00) (00) (00) (77) (01) (00) (00) (0E) (01) 

(00) (00) (A9) (01) (00) (00) (0A) (00) (00) (00) 


Fillet at Given Position (GFLT - short format) 

(C5) (24) (50) (00) (50) (00) (4B) (00) (0E) (01) (7D) (00) (0A) (00) (AF) (00) 

(0E) (01) (El) (00) (0A) (00) (13) (01) (0E) (01) (45) (01) (0A) (00) (77) (01) 

(0E) (01) (A9) (01) (0A) (00) 


Fillet at Current Position (GCFLT) 

(85) (40) (4B) (00) (00) (00) (0E) (01) (00) (00) (7D) (00) (00) (00) (0A) (00) 

(00) (00) (AF) (00) (00) (00) (0E) (01) (00) (00) (El) (00) (00) (00) (0A) (00) 

(00) (00) (13) (01) (00) (00) (0E) (01) (00) (00) (45) (01) (00) (00) (0A) (00) 

(00) (00) (77) (01) (00) (00) (0E) (01) (00) (00) (A9) (01) (00) (00) fOA) (00) 

( 00 ) ( 00 ) 


Fillet at Current Position (GCFLT - short format) 


(85) (20) (4B) (00) (0E) (01) (7D) (00) (0A) (00) (AF) (00) (0E) (01) (El) (00) 
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Fillet at Current Position (GCFLT - short format) (continued) 

(OA) (00) (13) (01) (0E) (01) (45) (01) (0A) (00) (77) (01) (0E) (01) (A9) (01) 

(0A) (00) 

Full Arc at Given Position (GFARC) 

(C7)(0C) (50) (00) (00) (00) (50) (00) (00) (00) (00) (00) (40) (00) 

Full Arc at Given Position (GFARC - short format) 

(Cl) (06) (50) (00) (50) (00) (00) (40) 

Full Arc at Current Position (GCFARC) 

(87) (04) (00) (00) (40) (00) 

Full Are at Current Position (GCFARC - short format) 

(87) (02) (00) (40) 

Image Data (GIMB) 

(92) (04) (00) (00) (03) (00) 

Label (GLRL) _ 

(D2) (05) (4C) (41) (42) (45) (4C) 

Line at Current Position (GCLINE) 

(81) (08) (FA) (00) (00) (00) (64) (00) (00) (00) 

Line at Current Position (GCLINE - short format) 

(81) (04) (FA) (00) (64) (00) 

Line at Given Position (GLINE) 

(Cl) (10) (50) (00) (00) (00) (50) (00) (00) (00) (FA) (00) (00) (00) (64) (00) 

( 00 ) ( 00 ) 

Line at Given Position (GLINE - short format) 

(Cl) (08) (50) (00) (50) (00) (FA) (00) (64) (00) 

Marker at Given Position (GMRK) 

(C2) (08) (82) (00) (00) (00) (5F) (00) (00) (00) 

Marker at Given Position (GMRK - short format) 

(C2) (04) (96) (00) (96) (00) 

Marker at Current Position (CGMRK) 

(82) (80) (96) (00) (00) (00) (96) (00) (00) (00) 
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Marker at Current Position (CGMRK - short format) 

(82) (04) (96) (00) (96) (00) 

Modify Path (GMPTH) __ 

(D8) (06) (06) (00) (01) (00) (00) (00) 

No-Operation (GNOP1) 

( 00 ) ~ 

Outline Path (GQPTH) _ 

(D4) (06) (00) (00) (01) (00) (00) (00) _ ~~ _ 

Partial Are at Given Position (GPARC) 

(E3) (1C) (20) (00) (00) (00) (20) (00) (00) (00) (64) (00) (00) (00) (64) (00) 

(00) (00) (00) (00) (40) (00) (00) (00) (20) (00) (00) (00) (40) (00) 

Partial Are at Given Position (GPARC - short format) 

(E3) (12) (20) (00) (20) (00) (64) (00) (64) (00) (00) (40) (00) (00) (20) (00) 

(00) (00) (40) (00) 

Partial Arc at Current Position (GCPARC) 

(A3) (14) (64) (00) (00) (00) (64) (00) (00) (00) (00) (00) (40) (00) (00) (00) 

(20) (00) (00) (00) (40) (00) 

Partial Arc at Current Position (GCPARC - short format) 

(A3) (0E) (64) (00) (64) (00) (00) (40) (00) (00) (20) (00) (00) (00) (40) (00) 

Pop (GPQP) ____ 

(3F) (00) 

Relative Line at Given Position (GRLINE) 

(El) (18) (50) (00) (00) (00) (50) (00) (00) (00) (FA) (00) (00) (00) (64) (00) 

(00) (00) (FA) (00) (00) (00) (50) (00) (00) (00) 

Relative Line at Given Position (GRLINE - short format) 

(El) (0C) (50) (00) (50) (00) (FA) (00) (64) (00) (FA) (00) (50) (00) 

Relative Line at Current Position (GCRLINE) 

(Al) (10) (FA) (00) (00) (00) (64) (00) (00) (00) (FA) (00) (00) (00) (50) (00) 

(00) (00) 

Relative Line at Current Position (GCRLINE - short format) 

(Al) (08) (FA) (00) (64) (00) (FA) (00) (50) (00) 
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Set Arc Parameters (GSAP) 

( 22 ) ( 10 ) ( 02 ) ( 00 ) ( 00 ) ( 00 ) ( 02 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) ( 00 ) 

( 00 ) ( 00 ) 

Set Arc Parameters (GSAP - short format) 

(22) (08) (02) (00) (02) (00) (00) (00) (00) (00) 

Push and Set Arc Parameters (GPSAP) 

(62) (10) (02) (00) (00) (00) (02) (00) (00) (00) (00) (00) (00) (00) (00) (00) 

( 00 ) ( 00 ) 

Push and Set Arc Parameters (GPSAP - short format) 

(62) (08) (02) (00) (02) (00) (00) (00) (00) (00) 

Set Background Color (GSBCOL) 

(25) (02) (01) (00) 

Push and Set Background Color (GPSBCOL) 

(65) (02) (01) (00) 

Set Background Indexed Color (GSBICOL) 

(A7) (04) (00) (06) (00) (00) 

Push and Set Background Indexed Color (GPSBICOL) 

(E7) (04) (00) (06) (00) (00) 

Set Background Mix (GSBMX) 

(0D) (02) 

Push and Set Background Mix (GPSBMX) 

(4D) (02) 

Set Character Angle (GSCA) 

(34) (08) (02) (00) (00) (00) (01) (00) (00) (00) 

Set Character Angle (GSCA - short format) 

(34) (04) (02) (00) (01) (00) 

Push and Set Character Angle (GPSCA) 

(74) (08) (02) (00) (00) (00) (01) (00) (00) (00) 

Push and Set Character Angle (GPSCA - short format) 


(74) (04) (02) (00) (01) (00) 
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Set Character Cell (GSCC) 

(33) (OE) (32) (00) (00) (00) (32) (00) (00) (00) (00) (00) (00) (00) (80) (00) 

Set Character Cell (GSCC - short format) 

(33) (0A) (32) (00) (32) (00) (00) (00) (00) (00) (80) (00) 

Push and Set Character Cell (GPSCC) 

(03) (OE) (32) (00) (00) (00) (32) (00) (00) (00) (00) (00) (00) (00) (80) (00) 

Push and Set Character Cell (GPSCC - short format) 

(03) (0A) (32) (00) (32) (00) (00) (00) (00) (00) (80) (00) 

Set Character Direction (GSCD) 

(3A) (01) 

Push and Set Character Direction (GPSDC) 

(7A) (01) 

Set Character Precision (GSCR) 

(39) (01) 

Push and Set Character Precision (GPSCR) 

(79) (01) 

Set Character Set (GSCS) 

(38) (00) 

Push and Set Character Set (GPSCS) 

(78) (00) __ 

Set Character Shear (GSCH) 

(35) (08) (01) (00) (00) (00) (05) (00) (00) (00) 

Set Character Shear (GSCH - short format) 

(35) (04) (01) (00) (05) (00) 

Push and Set Character Shear (GPSCH) 

(75) (08) (01) (00) (00) (00) (05) (00) (00) (00) 

Push and Set Character Shear (GPSCH - short format) 

(75) (04) (01) (00) (05) (00) ” 

Set Clip Path (GSCPTH) __ 

(B4) (06) (04) (00) (01) (00) (00) (00) ~ 
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Set Color (GSCQL) __ 

(OA) (01) 

Push and Set Color (GPSCOL) 

(4A) (01) _ ~ _ 

Set Current Position (GSCP) 

(21) (08) (32) (00) (00) (00) (64) (00) (00) (00) 

Set Current Position (GSCP - short format) 

(21) (04) (32) (00) (64) (00) 

Push and Set Current Position (GPSCP) 

(61) (08) (32) (00) (00) (00) (64) (00) (00) (00) 

Push and Set Current Position (GPSCP» short format) 
(61) (04) (32) (00) (64) (00) 

Set Extended Color (GSECOL) 

(26) (02) (01) (00) 

Push and Set Extended Color (GPSECOL) 

( 66 ) ( 02 ) ( 01 ) ( 00 ) 

Set Fractional Line Width (GSFLW) 

(11) (02) (00) (01) 

Push and Set Fractional Line Width (GPSFLW) 

(51) (02) (00) (01) 

Set Indexed Color (GSICOL) 

(A6) (04) (00) (01) (00) (00) 

Push and Set Indexed Color (GPSICOL) 

(E6) (04) (00) (01) (00) (00) 

Set Individual Attribute (GSIA) 

(14) (06) (01) (01) (00) (01) (00) (00) 

Push and Set Individual Attribute (GPSIA) 

(54) (06) (01) (01) (00) (01) (00) (00) 

Set Line End (GSLE) 


(1A) (01) 
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Push and Set Line End (GPSLE) _ 

(5A) (01) 

Set Line Join (GSLJ) 

(IB) (01) 

Push and Set Line Join (GPSLJ) 

(5B) (01) 

Set Line type (GSLT) 

(18) (01) 

Push and Set Line Type (GPSLT) _ 

(58) (01) 

Set Line Width (GSLW) _ 

(19) (01) 

Push and Set Line Width (GSFLW) _ 

(59) (01) ~ 

Set Marker Cell (GSMC) _ 

(37) (0A) (32) (00) (00) (00) (32) (00) (00) (00) (80) (00) 

Set Marker Cell (GSMC - short format) 

(37) (06) (32) (00) (32) (00) (80) (00) 

Push and Set Marker Cell (GPSMC) _ 

(77) (0A) (32) (00) (00) (00) (32) (00) (00) (00) (80) (00) 

Push and Set Marker Cell (GPSMC - short format) 

(77) (06) (32) (00) (32) (00) (80) (00) " 

Set Marker Set (GSMS) _ 

(3C) (00) 

Push and Set Marker Set (GPSMS) 

(7C) (00) ~ ~~ 

Set Marker Symbol (GSMT) 

(29) (01) 

Push and Set Marker Symbol (GPSMT) 


(69) (01) 
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Set Mix (GSMX) _ 

(OC) (02) 

Push and Set Mix (GPSMX) 

(4C) (02) 

Set Model Transform (GSTM) 

(24) (1C) (00) (01) (CC) (OC) (00) (00) (02) (00) (00) (00) (00) (00) (00) (00) 

(00) (00) (00) (00) (02) (00) (14) (00) (00) (00) (14) (00) (00) (00) 

Set Model Transform (GSTM - short format) 

(24) (10) (00) (01) (CC) (0C) (00) (02) (00) (00) (00) (00) (00) (02) (14) (00) 

(14) (00) 

Push and Set Model Transform (GPSTM) 

(64) (1C) (00) (01) (CC) (0C) (00) (00) (02) (00) (00) (00) (00) (00) (00) (00) 

(00) (00) (00) (00) (02) (00) (14) (00) (00) (00) (14) (00) (00) (00) 

Push and Set Model Transform (GPSTM - short format) 

(64) (10) (00) (01) (CC) (0C) (00) (02) (00) (00) (00) (00) (00) (02) (14) (00) 

(14) (00) 

Set Pattern Reference Point (GSPRP) 

(A0) (0A) (00) (00) (00) (00) (00) (00) (00) (00) (00) (00) 

Set Pattern Reference Point (GSPRP - short format) 

(A0) (06) (00) (00) (00) (00) (00) (00) 

Push and Set Pattern Reference Point (GPSPRP) 

(E0) (0A) (00) (00) (00) (00) (00) (00) (00) (00) (00) (00) 

Push and Set Pattern Reference Point (GPSPRP - short format) 

(E0) (06) (00) (00) (00) (00) (00) (00) 

Set Pattern Set (GSPS) 

(08) (00) 

Push and Set Pattern Set (GPSPS) 

(48) (00) 

Set Pattern Symbol (GSPT) 


(28) (0B) 
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Push and Set Pattern Symbol (GPSFT) 

(09) (OB) 

Set Pick Identifier (GSPIK) 

(43) (04) (02) (00) (00) (00) 

Push and Set Pick Identifier (GPSPIK) 

(23) (04) (02) (00) (00) (00) 

Set Stroke Line Width (GSSLW) __ 

(15) (06) (00) (00) (80) (00) (00) (00) 

Set Stroke Line Width (GSSLW - short format) 

(15) (04) (00) (00) (80) (00) 

Push and Set Stroke Line Width (GPSSLW) 

(55) (06) (00) (00) (80) (00) (00) (00) 

Push and Set Stroke Line Width (GPSSLW - short format) 

(55) (04) (00) (00) (80) (00) 

Set Viewing Transform (GSTV) 

(31) (1C) (00) (00) (CC) (0C) (00) (00) (02) (00) (00) (00) (00) (00) (00) (00) 

(00) (00) (00) (00) (02) (00) (00) (00) (00) (00) (00) (00) (00) (00) 


Set Viewing Transform (GSTV - short format) 

(31) (10) (00) (00) (CC) (0C) (00) (02) (00) (00) (00) (00) (00) (02) (00) (00) 

( 00 ) ( 00 ) 


Set Viewing Window (GSVW) 

(27) (12) (80) (3C) (00) (00) (00) (00) (20) (03) (00) (00) (00) (00) (00) (00) 
(20) (03) (00) (00) 


Set Viewing Window (GSVW - short format) 

(27) (0A) (80) (3C) (00) (00) (20) (03) (00) (00) (20) (03) 


Sharp Fillet at Current Position (GCSFLT) 

(A4) (A0) (4B) (00) (00) (00) (2C) (01) (00) (00) (64) (00) (00) (00) (96) (00) 

(00) (00) (7D) (00) (00) (00) (00) (00) (00) (00) (96) (00) (00) (00) (96) (00) 

(00) (00) (AF) (00) (00) (00) (2C) (01) (00) (00) (C8) (00) (00) (00) (96) (00) 

(00) (00) (El) (00) (00) (00) (00) (00) (00) (00) (FA) (00') (00) (00) (96) (00) 

(00) (00) (13) (01) (00) (00) (2C) (01) (00) (00) (2C) (01) (00) (00) (96) (00) 

(00) (00) (45) (01) (00) (00) (00) (00) (00) (00) (5E) (01) (00) (00) (9B) (00) 

(00) (00) (77) (01) (00) (00) (2C) (01) (00) (00) (90) (01) (00) (00) (96) (00) 

(00) (00) (A9) (01) (00) (00) (00) (00) (00) (00) (C2) (01) (00) (00) (9B) (00) 
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Sharp Fillet at Current Position (GCSFLT) (continued) 

(00) (00) (00) (80) (00) (00) (00) (40) (00) (00) (00) (30) (00) (00) (00) (10) 

(00) (00) (00) (08) (00) (00) (00) (04) (00) (00) (00) (02) (00) (00) (00) (01) 

( 00 ) ( 00 ) 


Sharp Fillet at Current Position (GCSFLT - short format) 

(A4) (60) (4B) (00) (2C) (01) (64) (00) (96) (00) (7D) (00) (00) (00) (96) (00) 

(96) (00) (AF) (00) (2C) (01) (C8) (00) (96) (00) (El) (00) (00) (00) (FA) (00) 

(96) (00) (13) (01) (2C) (01) (2C) (01) (96) (00) (45) (01) (00) (00) (5E) (01) 

(9B) (00) (77) (01) (2C) (01) (90) (01) (96) (00) (A9) (01) (00) (00) (C2) (01) 

(9B) (00) (00) (80) (00) (00) (00) (40) (00) (00) (00) (30) (00) (00) (00) (10) 

(00) (00) (00) (08) (00) (00) (00) (04) (00) (00) (00) (02) (00) (00) (00) (01) 

( 00 ) ( 00 ) 
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GPI Functions Supported only by a Normal-PS 


The following functions are invalid for a Micro~PS„ 
GpiAssociate 
GpiBeginElement 
GpiCallSegmentMatrix 
GpiCloseSegment 
GpiCorrelateChain 
GpiCorrelateFrom 
GpiCorrelateSegment 
GpiDeleteElement 
GpiDeleteElementRange 
GpiDeleteElementsBetweenLabels 
GpiDeleteSegment 
GpiBeleteSegments 
GpiDrawChain 
GpiDrawDynamics 
GpiDrawFrom 
GpiDrawSegment 
GpiElement 
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GpiEndElement 

GpiErrorSegmentData 

GpiGetData 

GpiLabel 

GpiOffsetElementPo inter 

GpiOpenSegment 

GpiPop 

GpiPutData 

GpiQueryAttrMode 

GpiQueryDefTag 

GpiQueryDrawControl 

GpiQueryDrawingMode 

GpiQueryEditMode 

GpiQueryElement 

GpiQueryElementPointer 

GpiQueryElementType 

GpiQuerylnitialSegmentAttrs 

GpiQuerySegmentAttrs 

Gp i Query SegmentNames 

GpiQuerySegmentPriority 

GpiQuerySegmentTransformMatrix 

GpiQueryStopDraw 

GpiQueryTag 

GpiQueryViewingTransformMatrix 

GpiRemoveDynamics 

GpiSetAttrMode 

GpiSetDefTag 

GpiSetDrawControl 

GpiSetDrawingMode 

GpiSetEditMode 

GpiSetElementPointer 
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GpiSetElementPointerAtLabel 

GpiSetlnitialSegmentAttrs 

GpiS et S egmentAttr s 

GpiSetSegmentPriority 

GpiSetSegmentTransformMatrix 

GpiSetStopDraw 

GpiSetTag 

GpiSetViewingTransformMatrix 

Note that GpiSetDrawControl/GpiQueryDrawControl are valid in a Micro-PS for 
the DCTLJDISPLAY, DCTL_BOUNDARY, DCTL_CORRELATE controls only 
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alternate mode. A mode used for defining which area segments formed by mul¬ 
tiple overlapping closed figures are considered part of the area interior. In alter¬ 
nate mode a figure segment is considered part of the area interior if, counting from 
infinity to a point in the segment, the number of figure boundary line crossings is 
odd. 

arbitrary page units. Page units that cause the PS page dimensions to be scaled 
to fit the available device output area causing the picture to be displayed as large 
as possible while retaining its correct aspect ratio. 

arc parameters. A drawing attribute that maps a unit circle to the required 
ellipse, controlling the shape and size of arcs drawn using GpiFullArc, 
GpiPartialArc, and the shape only of GpiPointArc. 

area bundle. A drawing or default attribute bundle structure containing the 
group of attributes used for area fill operations. 

apect ratio. The width to height ratio of a picture or shape. 

association. A process by which a device context is linked to a presentation space 
in order to identify the target output device for that presentation space. 

attribute mode. A PS mode that enables the current value of a drawing attribute 
to be automatically saved in a LIFO stack when a new value is set, and subse¬ 
quently restored using a pop operation. 

average character width. The average character width of a font in world coor¬ 
dinates. 

background color attribute. A picture attribute defining the background color 
to be used by subsequent drawing primitives. Background color is a global attri¬ 
bute. 

background mix. A picture attribute defining the background mix mode to be 
used by subsequent drawing primitives. Background mix is a global attribute. 
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baseline. A reference line along which characters are positioned horizontally. 

BitBlt. A Bit Block Transfer operation that enables the rapid transfer of a rectan¬ 
gular block of pixel image data between a bitmap and raster device. 

bitmap. A rectangular array of pixel image data stored in memory that can be 
used as the target of any output drawing operation (including BitBlt) or the source 
of a BitBlt operation. 

boundary accumulation. A process by which the coordinates of the smallest 
rectangle into which the entire picture will fit, are accumulated in model space. 

bundle. A drawing or default attribute structure containing the group of attri¬ 
butes used for one particular type of primitive drawing operation (i.e., characters, 
lines, areas, markers, or imagq/BitBlt). 

cached Micro-PS. An associated Micro-PS/WindowDC pair for use by applica¬ 
tions where the large number of windows make it impractical to allocate a 
separate Micro-PS and DC for each window. 

chained segment. A root segment with its chained segment attribute set and 
that forms part of the picture chain. 

character angle attribute. A character bundle picture attribute defining the 
baseline angle for outline and mode two raster font characters. This affects the 
position and orientation of outline font characters and the position of mode two 
raster font characters. 

character box attribute. A character bundle picture attribute controlling the 
height and width of outline font characters and the spacing of outline and mode 
two raster font characters. 

character bundle. A drawing or default attribute structure containing the group 
of attributes used by character drawing primitives. 

character cell. Synonym for character box. 

character direction attribute. A character bundle picture attribute defining 
the direction (left to right, right to left, top to bottom, or bottom to top) of outline 
and mode two raster characters. 

character mode attribute. A character bundle picture attribute specifying the 
mode or precision with which characters should be drawn in terms of which 
character (box, shear, and angle) attributes must be honored for raster font 
characters, and which are optional, and whether or not and the font must be an 
outline font. 

character precision. Synonym for character mode. 

character set. A character bundle picture attribute defining the id of the font to 
be used for drawing characters. 
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character shear attribute. A character bundle picture attribute defining the 
shear angle of outline and mode two raster characters. This affects the position 
and shape of outline font characters and the position of mode two raster font 
characters (drawn vertically using the top to bottom or bottom to top character 
direction attribute). 

clip path. A path that has been converted to a clip path using GpiSetClipPath to 
define a complex clipping shape. Although paths are defined in world coordinates, 
the clip path is frozen in device coordinates at the time of the conversion from a 
path to a clip path. 

clip region. A PS environment attribute used for clipping to a complex shape 
defined by one or more rectangles in device coordinates. 

clipping. A process by which all output that is outside a defined clip boundary is 
removed (or clipped) and only that inside the clip boundary is displayed. 

codepage. A mapping between a set of codepoints and a set of graphic characters. 

color attribute. A picture attribute defining the foreground color to be used by 
subsequent drawing primitives. Color is a global attribute. 

color table. See logical color table. 

correlation. A process by which drawing primitives are compared for intersection 
against a rectangular pick aperture for the purpose of determining which primi- 
tive or primitive group in a picture is at a given position on the display. This is 
normally used to identify the primitive or primitive group selected by a user (e.g., 
using a mouse and pointer). 

cosmetic line width. A line bundle picture attribute defining the thickness of 
subsequent lines. Cosmetic line width consists of an integer and fractional part 
defining a multiplier to be applied to a line of unit thickness (e.g., one pel). 

CSD. Corrective Service Diskette. 

current position. A picture attribute defining the current drawing position in 
world coordinates for a number of GPI output functions. Current position is 
updated by most output functions. 

default attribute. An attribute defining the actual attribute value to be used for 
drawing when the corresponding drawing attribute is specified as default. 

default page coordinate space. A coordinate space immediately above the PS 
page representing the picture defined in page coordinates without any scaling or 
scrolling applied (by the default viewing transform). 

default viewing transform matrix. A PS environment attribute providing a 
transformation from default page coordinate space to the PS page and used for 
scaling and scrolling the entire picture. 
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detectable segmento A segment with its detectable segment attribute set mak¬ 
ing it eligible for returning a hit from a retained correlation operation. 

device context (DC). A logical output device defining the target of drawing 
operations. A device context typically identifies a display window, an instance of a 
shared output device such as a printer, a bitmap, or a virtual output device such 
as a MetaFile. 

device coordinate space. The coordinate space of the device. 

device coordinates. Coordinates specified in device units, normally pels. 

device drawing context (DDC). That part of the device context data owned by 
the Presentation Driver. 

device driver interface (DDI). The presentation driver interface. 

device transform. A transform from the PS page to device space that, together 
with the device resolution, provides the required page units in the page. Device 
transform can be viewed as a PS environment attribute rather than a drawing 
attribute (although it is, in fact, actually owned by the device rather than the PS). 

direct DC. A device context used for direct printing. 

direct printing. Output to a hard copy device that is passed directly to the device 
for immediate output, bypassing the print queue and spooler. 

disassociation. A process by which a presentation space and device context 
association is broken. 

display driver. A Presentation Driver used to output to the display device. 

dithering. A process by which RGB colors that are not available on the device are 
simulated by alternating the colors used for different pels when drawing an area. 

draw controls. A selection of modal PS options that control subsequent drawing 
operations (i.e., erase before draw, display, enable boundary accumulation, draw 
dynamics, enable correlation). 

drawing attribute. A picture attribute that controls the appearance (e.g., color) 
of subsequent drawing primitives and may be varied during drawing for picture 
construction. 

drawing mode. A PS mode controlling whether output primitives are drawn, 
accumulated in retained segments, or both. 

drawing order. A sequence of bytes used for representing a drawing primitive or 
attribute in a retained graphics or MetaFile segment. An order is the smallest unit 
of an element. 

drawing primitive. A picture function that produces output to a device. 
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dynamic segment. A chained segment with its dynamic segment attribute set 
that can be rapidly drawn and removed using XOR mix mode without affecting the 
picture beneath it. 

BRIVDATA. A structure containing device dependant driver data (such as device 
type, printer, and job properties) required when opening a printer DC. 

element. A group of one one more related drawing orders in a retained segment 
or MetaFile, typically generated by a single GPI function call, and treated as a 
single entity addressed by the element pointer for segment editing purposes. 

element pointer. An element offset used to identify the target element or ele¬ 
ments of a retained segment editing operation. 

em height. The height of the em square representing the font point size in world 
coordinates. For an outline font, this is the same as the height of the character box 
attribute. 

em inc. The width of the em square in world coordinates. For an outline font, this 
is the same as the width of the character box attribute. 

em square. A square of size equivalent to the font point size in world coordinates. 

environment and resource functions. The collection of environment attri¬ 
butes and resources (e.g., color tables, fonts) owned by the presentation space. 
Apart from incremental loading of resources as required, these should remain 
constant during drawing. 

environment attribute. A presentation space attribute (e.g., default view ma¬ 
trix) that controls the appearance of the entire picture. PS environment attributes 
should not be varied during drawing for picture construction. 

external leading. The maximum vertical font spacing in world coordinates that 
can be added to the maximum baseline extent without affecting the pleasing 
appearance of the text. 

face name. The full typeface name for a font (e.g., "Courier Bold Italic”). Fonts 
within a single font file will frequently have different face names. 

family name. A name similar to the face name but more general (e.g., "Courier” 
is the equivalent family name of face name "Courier Bold”). Fonts within a single 
font file will normally have a common family name. 

fast chaining. A segment attribute providing a performance hint to the system 
that optionally allows the system to omit the drawing attribute reset that would 
otherwise occur at the start of each new root segment. Note that fast chaining does 
not guarantee that no reset will be performed. 

font. A collection character glyphs or symbols defining the character shapes for a 
particular typeface required by one or more codepages. 

font metrics. A collection of parameters describing the attributes of a font. 
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geometric line width attribute. A line bundle picture attribute defining the 
thickness of geometric wide lines created using GpiModifyPath or GpiStrokePath. 

geometric wide line,, A line with thickness specified in world coordinates and 
scaled using the GPI transforms. The line interior is filled using an area fill 
pattern. Geometric wide lines are constructed using the path functions. 

global attribute. A bundle attribute (i.e., color, mix, background color, or back¬ 
ground mix) that occurs in multiple attribute bundles and can be set in all bundles 
simultaneously using a single function call (e.g., GpiSetColor). 

glyph. A graphic symbol typically representing a single font character. 

GPI, Graphics Programming Interface. 

graphics engine. The component that, together with the device drivers, im¬ 
plements the GPI graphics drawing algorithms. 

graphics field, A PS environment drawing attribute that defines a clipping rec¬ 
tangle in the PS page. 

graphics segment, A graphics object containing a group of related elements (or 
drawing orders). 

image. A rectangular array of pixel data. 

Image bundle. A drawing or default attribute structure containing the group of 
attributes used by image and BitBlt drawing primitives. 

index mode. A color table mode in which colors are specified as index values 
referencing corresponding RGB values in the color table. 

Info DC. A device context used only for querying information about the device, 
information context. See Info DC. 

INI file. A file (e.g., OS2.INI, OS2SYS.INI) managed by the system and used to 
store application and system profile information (e.g., printer properties). 

instance transform. A model transform attribute specified with 
GpiCallSegmentMatrix. 

internal leading, A vertical distance in world coordinates equal to the difference 
between the maximum baseline extent and the em height. 

internal segment prolog, A segment prolog located before the first element of a 
segment, used internally to store the segment transform and viewing transform 
and not directly visible to an application. 

kerning, A process by which the spacing between certain pairs of characters (e.g., 
To) in a proportional font is adjusted such that the character boxes overlap to 
provide a further improvement in the appearance of text. 
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Icid. Locally coded identifier (synonym for set id). 

line bundle. A drawing or default attribute structure containing the group of 
attributes used by line drawing primitives. 

line end attribute. A line bundle picture attribute defining the shape to be used 
for the ends of geometric wide lines created using GpiModifyPath or 
GpiStrokePath. 

line join attribute. A line bundle picture attribute defining the shape to be used 
for the joins in geometric wide lines created using GpiModifyPath or 
GpiStrokePath. 

line type attribute. A line bundle picture attribute defining the style (e.g., dot¬ 
ted, solid) of subsequent lines. 

line width attribute. A line bundle picture attribute defining the cosmetic line 
width of subsequent lines. 

logical color table. A map of index to RGB color values where the index value 
may be used as a color attribute. 

logical font. A collection of font attributes describing the characteristics of a 
required font. 

lower caise ascent. The maximum distance that a lower case character of the font 
ascends above the baseline in world coordinates. 

lower case descent. The maximum distance that a lower case character of the 
font descends below the baseline in world coordinates. 

marker. A stand alone symbol positioned by its center and typically used to 
represent a point on a graph. 

marker box attribute. A marker bundle picture attribute defining the size of 
outline markers drawn using an outline font or marker set. 

marker bundle. A drawing or default attribute structure containing the group of 
attributes used by marker drawing primitives. 

marker cell. Synonym for marker box. 

marker set. A marker bundle picture attribute defining the id of the marker set 
or font to be used for drawing markers. 

marker symbol. A marker bundle picture attribute defining the marker or font 
codepoint to be used for drawing markers. 

maximum ascender. The maximum distance that a font character ascends above 
the baseline in world coordinates. 

maximum baseline extent. The maximum vertical extent of font characters in 
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world coordinates determined by the sum of the maximum ascender plus the 
maximum descender. 

maximum character increment. The maximum horizontal character incre¬ 
ment of a font in world coordinates. For a universal font, this represents the 
maximum for the font rather than the maximum for a particular codepage. 

maximum descender. The maximum distance that a character in the font de¬ 
scends below the baseline in world coordinates. 

Memory DC. A device context into which a bitmap may be selected in order to use 
the bitmap as the source or target of a BitBlt operation or the target of any drawing 
operation. 

MetaFile. A picture interchange file in architected SAA format held as a disk file 
or in memory as a memory MetaFile. 

MetaFile DC. A device context used for recording a MetaFile. 

Micro-PS. A presentation space that requires less memory and provides reduced 
function compared to a Normal-PS. 

mix attribute. A picture attribute defining the foreground mix mode to be used 
by subsequent drawing primitives. Mix is a global attribute. 

mix mode. A mode defining the logical operation used to combine new output with 
the existing color of the pels at the drawing position to produce the final output. 

model space. A conceptual coordinate space between world and page coordinates 
in which the picture is constructed by the output of the model transform matrix. 

model transform matrix. A drawing attribute that defines a transformation 
from world coordinate space to model space and is intended for picture modeling 
purposes. 

monospaced font. A font in which equal spacing is used for all characters. 

non-retained graphics. Graphics output primitives and attributes that are im¬ 
mediately drawn and then discarded. 

Normal-PS. A full presentation space capable of supporting all GPI functions. 

outline font. A font in which the shape of each character is defined by a sequence 
of vector strokes and curves defining a closed figure that is optionally filled. 

page coordinate space. A conceptual coordinate space immediately above de¬ 
vice space in which the picture is constructed by the output of the default viewing 
transform matrix. 

page units. Application defined coordinates of the PS page. 

page viewport. A rectangle in device coordinates which, together with the PS 
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page dimensions, defines the device transform matrix. The page viewport repre¬ 
sents the area of the output device in which the PS page is displayed and it is 
neither a clipping rectangle nor the same as the window rectangle on a display, 

path 0 An object defined in world coordinates by a sequence of drawing primitive 
and attribute functions issued between GpiBeginPath and GpiEndPath, A path 
can be used for defining a filled area, a complex clipping shape, an outline, and for 
drawing geometric wide lines. 

pattern attribute. An area bundle picture attribute defining the fill pattern or 
font codepoint to be used for area fill operations. This attribute is ignored for 
bitmaps that are used as area fill patterns. 

pattern reference point. An area bundle picture attribute defining the pattern 
origin to be used for area fill operations. 

pattern set attribute. An area bundle picture attribute defining the pattern set, 
font, or bitmap id to be used for area fill operations. 

pel. A picture element representing the smallest addressable point of a raster 
device. 

PIF. Picture Interchange File (an earlier IBM picture interchange architecture 
standard similar to the MetaFile architecture). 

pick aperture. A rectangle against which drawing primitives are compared for a 
correlation hit. 

picture functions. Drawing primitives and attribute functions that may be var¬ 
ied during drawing for picture construction purposes. 

pixel. Synonym for pel. 

print queue. The queue used by the spooler for queued print jobs. 

print queue processor. The component responsible for directly outputting a 
dequeued print job to the appropriate device and applying any queue processor 
parameters. 

point. A unit of 1/72 inches used in printing. 

point size. A measure of font character height in points. The point size is not 
defined in terms of any measurable characteristic of a visible character. 

presentation driver. A Presentation Manager device driver that converts the 
graphics functions presented at the Device Driver Interface (DDI) into low level 
OS/2 Kernel Device Driver requests or, in the case of a certain adapters (such as 
displays), interfaces directly with the adapter hardware. 

presentation space (PS). The object that owns the device independent resources 
and environment attributes and that can optionally be used to store or retain a 
complete graphics picture. 



310 


OS/2 PRESENTATION MANAGER CPI 


proportional font. A font in which the characters are spaced according to the 
widths of the individual characters in order to improve appearance. 

psychometric RGB. A system by which increased RGB value yields a visually 
linear increase in intensity rather than one based on photon intensity. 

PS page. The presentation space page. This is a coordinate space with application 
defined coordinates in which an application may define a picture in device inde¬ 
pendent coordinates. 

PS size. The dimensions of the presentation space page. These dimensions repre¬ 
sent the area in page coordinates space that is displayed in the page viewport on 
the output device. 

queue processor. See print queue processor. 

queued DC. A device context used to print queued output via the spooler. 

queued printing. Output to a hard copy device that is enqueued on a print queue 
for printing in sequence with other print jobs using the spooler. 

raster font. A font in which the shape of each individual character is defined by 
a rectangular pixel image or bitmap. 

realizable color table. A color table that may be realized by using the RGB color 
table values to load the physical device palette in order to obtain the closest 
possible match to the requested colors. 

region. An object defined by one or more rectangles in device coordinates that can 
be used for area fill or converted to a clip region. 

retained graphics. A PS mode in which the entire graphics picture is stored as 
a collection of chained and called graphics segments in the PS retained graphics 
segment store for subsequent display and editing. 

RGB color. A color defined by a one byte red, a one byte blue, and a one byte green 
value. 

RGB mode. A color table mode in which colors are specified directly as RGB 
values. 

root segment. S5uionym for chained segment. 

rop code. A code defining the mix mode for a BitBlt operation. A BitBlt rop code 
value defines a three way mix operation combining source, pattern, and target 
original pixel values to produce a final target output value. 

SAA. Systems Application Architecture (a common application architecture for 
IBM systems). 


segment attributes. The properties of a graphics segment that apply to the 
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whole segment (i.e., detectable, visible, chained, dynamic, fast chaining, propagate 
detectability, propagate visibility). 

segment idL A 4 byte segment identifier that must be equal to or greater than 
zero. Segment identifiers other than zero must be unique within a retained 
graphics picture or a MetaFile. 

segment prologc A group of orders terminated by an end prolog order located at 
the start of a graphics segment that has its prolog segment attribute set. Segment 
Prologs are not supported by the GPI except in MetaFiles. 

segment transform. A model transform stored in the internal prolog of a seg¬ 
ment. 

set id. An application defined identifier used to identify a bitmap as an area fill 
pattern or a logical font as a character set, marker set, or area fill pattern. 

soft font. A device (e.g., printer) font in a format that enables it to be stored on 
and installed from a disk or diskette. 

spooler. The component that handles printing of queued output via the print 
queue. 

tag. A drawing attribute that defines a value to be associated with a group of one 
or more elements or drawing orders in a segment for the purpose of identifying the 
position of a subsequent correlate hit. 

translation. A transformation operation producing a positional change. 

typeface. The name used to describe the appearance or style of a particular font 
(e.g., Roman). 

viewing limits. A drawing attribute that defines a clipping rectangle in model 
space. 

viewing transform matrix. A drawing attribute that defines a transformation 
from model space to default page coordinate space. 

winding mode. A mode used for defining which area segments formed from 
multiple overlapping closed figures are considered part of the area interior. In 
winding mode figure, boundary lines drawn in one direction can be considered to 
have a weight of +1 and those in the opposite direction a weight of -1. A figure 
segment is considered to be part of the area interior if, counting from infinity to a 
point in the segment, the net weight of the figure boundary line crossings is 
non-zero. 

world coordinates. The coordinate space in which an application specifies its 
coordinates for drawing. 

WYSIWYG. What-You-See-Is-What-You-Get (terminology used to describe consis¬ 
tency between the appearance of the same output on two different devices such as 
a display and printer). 
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x device resolution. For a raster font, this is the horizontal resolution in pels- 
per-inch of the device for which the font was designed. For an outline font, it is the 
width of the em square rectangle in font definition space in which the font was 
defined. 

x height. The height above the baseline of lower case characters (excluding 
ascenders) in world coordinates, typically represented by the height of lowercase 

6 9 

X. 

y device resolution. For a raster font, this is the vertical resolution in pels-per- 
inch of the device for which the font was designed. For an outline font, it is the 
height of the em square rectangle in font definition space in which the font was 
defined. 
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Alternate mode area fill, 81 
Arc functions, see Curve functions 
Arc parameters, 76—78. See also 
Non-bundle attributes 
Area, 6. See also Path area 
Area bundle, 6, 61, 79-80 
Area drawing functions, 79-81 
Area fill using regions, 170 
Area primitives, 81 
AREABUNDLE, see Area bundle 
Associate option on GpiCreatePS, 49 
Association, 2, 45 
Attributes: 

default, 7, 63-64, 199 
drawing, 5—6 
querying, 64 
resetting, 64-65 

Attribute bundles, 5-6, 59-61. See 
also Area bundle; Character 
bundle; Image bundle; Line 
bundle; Marker bundle 
Attribute functions, 60-62 
Attribute mode, 62-63, 159 
ATTRCHAINED segment 
attribute, 182 

ATTR_DETECTABLE segment 
attribute, 181, 192 
ATTRJDYNAMIC segment 
attribute, 182, 185 
ATTR_FA8TCHAIN segment 
attribute, 182 

ATTR_PROP_DETE CTABLE 
segment attribute, 182, 192 
ATTR_PROP_VIS IBLE segment 
attribute, 182 

ATTR_VISIBLE segment attribute, 
182, 192 


BitBlt, 6, 85-89, 

BitBlt functions, 84-90 
Bitmap: 

changing ownership, 129, 132 

creation, 128, 131 

data format, 130 

data transfer, 129 

definition in resource file, 128 

deletion, 129 

drawing to, 131-132, 262 

file format, 130-131 

format conversion, 127, 129-130 

modification by driver, 127 

ownership, 85-86 

recording in MetaFile, 202 

selection, 129 

set id, 112 

stretching and compression, 87, 
128 

supported formats, 126—127 
use as area fill pattern, 112 
use with PM_Q_STD print 
format, 234 

use with realizable color table, 
127, 147 

Bitmap dimension functions, 131 
Bold font simulation, 108 
Boundary accumulation, 8-9, 194, 
199, 200 

Break_Extra spacing, 71 
Bundle, see Attribute bundles 
BITMAPINFO, 129, 130 
BITMAPINFOHEADER, 129, 130 


Cached Micro-PS, 2 
Character: 


horizontal spacing, 107, 110 
output, 6 

position recorded in MetaFile, 109 
vertical spacing, 106—107 
Character angle attribute, 67 
Character box attribute, 66-67, 110 
Character bundle, 6, 60-61, 65-69 
Character cell attribute, 66-67 
Character direction attribute, 69 
Character functions, 65-71 
Character mode attribute, 66 
Character precision attribute, 66 
Characters, see Fonts 
Character set attribute, 66 
Character shear attribute, 68 
Character string primitives, 70 
CHARBUNDLE, see Character 
bundle 

Char_Extra spacing, 70—71 
Clip path, 94-96, 169 
Clip region, 169-171 
Clipping, 168-171 
Code pages, 111-112 
Color attribute: 
area, 79 

area background, 79 
character, 65 
character background, 65 
image, 84 

image background, 84 
line, 71 
marker, 82 

marker background, 82 
Color queries, 148 
Color table, See also Logical color 
table creation 
default, 143-145 
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index mode, 143, 146 
option on GpiPlayMetaFile, 198 
realizable, 146, 147—148 
recording in MetaFile, 201, 203 
RGB mode, 143, 146 
standard, 143-145 
Coordinate: 

avoiding overflow, 158 
format option on GpiCreatePS, 9, 
48-49 

limits 9, 157-158 
of rectangle boundary, 10 
Correlation, 9, 190—193 
Current position, 3. See also 
Non-bundle attributes 
Curve functions, 71-78 
Curve primitives, 73—75 


DC, see Device context 
DCTL_BOUNDARY draw control, 
184, 194 

DCTL_CORRELATE draw control, 
184,190-191 

DCTL_DISPLAY draw control, 184 
DCTL_DYNAMIC draw control, 

184, 185 

DCTLJERASE draw control, 184 
Default attribute functions, see 
Attributes, default 
Default viewing transform, 6, 162, 
196 

DevEscape, 5, 49-50, 203 
Device context, 2, 41—43 
direct, 42 

display window, 41-42 
info, 42 
memory, 43 
ownership, 2 
queued, 42 
MetaFile, 42 

Device drawing context, 2 
Device driver, 1-2. See also 
Presentation driver 
Device Driver Interface (DDI), 1—2 
Device independence, 152 
Device resolution for font selection, 
109 

Device transform, 163-165 
Device types valid for use with GPI, 
1 

DevOpenDC parameters, 257-262 
DevPostDeviceModes, 229-230, 
231, 232 

DevQueryCaps, 50 
DevQueryHardcopyCaps, 5, 232 
Direct printing, 219-220 
Dithering, 145 

DosPrint spooler API, 235—236 
DosPrintDest functions, 235 


DosPrintJob functions, 235 
DosPrintQ functions, 235-236 
Draw and retain mode, 180—181 
Draw controls, 183-184 
Draw mode, 180—181 
Drawing modes, 180-181 
DRIVDATA, 229-230, 231, 259-260 
Dynamic segments, 185—186 


Edit mode, 186-187 

Element pointer, 186 

Elements, 176 

Em Square, 107 

Engine, graphics, 1—2 

Environment functions (of PS), 7—8 

Error: 

display, 12 
handling, 11-13 

PMERR_COORDINATE_OVERFL 
OW, 270 

PMERR_PATH_LIMIT_EXCEEDE 
D, 81, 91 

PMERR_PS_BUSY, 10 
return codes, 11 
severity, 12 


Fast chaining, 182 
FIXED numbers, 10-11 
Font: 

Adobe TYpe 1, 99, 100, 101, 104 
device, 99, 109 
lEmHeight metric, 107 
lEmlnc metric, 107 
lExternalLeading metric, 106—107 
match number, 108, 203 
metrics, 104—107 
monospaced, 101 
outline, 101 
private, 100—101 
proportional, 101 
public, 100-101 
raster, 101, 106 
recording in MetaFile, 109 
scaling using character box, 
109-110 

scaling (outline) to match raster, 

110 

selection, 106, 107 
selection indicators, 108 
setting horizontal pitch, 110 
setting point size using character 
box, 110 
sources, 99 

sXDeviceRes metric, 106, 109—110 
sYDeviceRes metric, 106, 109—110 
szFacename metric, 106 
szFamilyname metric, 106 


typeface, 106 

with PM_Q_STD print format, 233 
Form code, 5 
Form selection, 232 


Geometric wide line attributes, 

90-91 

Geometric wide lines, 93—94 
Global attributes, 6, 60 
GPI graphics subsystem structure, 
1-2 

GPI layer, 1-2 
GPI picture and 

environmeni/resource model, 

7-8 

GpiAssociate, 45, 199, 201 
GpiBeginArea, 81 
GpiBeginPath, 91 
GpiBitBlt, 132 
in retain mode, 7 
parameters, 87-89 
source and target combinations, 

85 

with PM_Q_STD print format, 234 
GpiBox, 75 

GpiCallSegmentMatrix, 160, 176 
GpiCharString, 70 
GpiCharStringAt, 70 
GpiCharStringPos, 70 
GpiCharStringPosAt, 70 
GpiCloseSegment, 176 
GpiCombineRegion, see Regions 
GpiConvert, 158 
GpiCorrelateChain, 191—193 
GpiCorrelateFrom, 191—193 
GpiCorrelateSegment, 191-193 
GpiCreateBitmap, 128, 131 
GpiCreateLogColorTable, 145—147 
GpiCreateLogFont, 107-109, 112 
GpiCreatePS, 47-49 
GpiCreateRegion, see Regions 
GpiDeleteBitmap, 129 
GpiDeleteElement, see Segment, 
editing 

GpiDeleteElementRange, see 
Segment, editing 

GpiDeleteElementsBetweenLabels, 
see Segment, editing 
GpiDeleteMetaFile, 195 
GpiDeleteSegment, see Segment, 
editing 

GpiDeleteSegments, see Segment, 
editing 

GpiDeleteSetld, 107, 112 
GpiDestroyPS, 46 
GpiDestroyRegion, see Regions 
GpiDrawChain, 179-180 
GpiDrawDynamics, 185 
GpiDrawFrom, 179-180 
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GpiDrawSegment, 179-180 
GpiElement, 176 
GpiEndArea, 81 
GpiEndPath, 91 
GpiEqualRegion, see Regions 
GpiErase, 50 

GpiErrorSegmentData, 13 
GpiExcludeClipRectangle, see Clip 
region 

GpiFillPath, 92 
GpiFullArc, 7a-74 
GPIF_SHORT coordinate format 
option, 157 
GpiGetData, 175-176 
Gpilmage, 85 

GpilntersectClipRectangle, see Clip 
region 

GpiLabel, 186 
GpiLine, 72 

GpiLoadBitmap, 128, 132 
GpiLoadFonts, 101 
GpiLoadMetaFile, 195 
GpiMarker, 84 
GpiModifyPath, 93-94 
GpiMove, 62—63. See also 
Non-bundle attributes 
GpiOffsetElementPointer, see 
Segment, editing 
GpiOffsetRegion, see Regions 
GpiOpenSegment, 176 
GpiOutlinePath, 93 
GpiPaintRegion, 7. See also 
Regions 

GpiPartialArc, 75 
GpiPlayMetaFile, 196-199 
GpiPointArc, 75 
GpiPolyFillet, 73 
GpiPolyFilletSharp, 73 
GpiPolyLine, 72 
GpiPolyMarker, 84 
GpiPolySpline, 73 
GpiPop, see Attribute mode 
GpiPtlnRegion, see Regions 
GpiPutData, 175-176 
GpiQueryArcParams, see 
Non-bundle attributes 
GpiQueryAttrs, 60 
GpiQueryAttrMode, see Attribute 
mode 

GpiQueryBackColor, see Global 
attributes 

GpiQueryBackMix, see Global 
attributes 

GpiQueryBitmapBits, 129 
GpiQueryBitmapDimension, see 
Bitmap dimension functions 
GpiQueryBoundaryData, 194 
GpiQueryCharAngle, see Character 
bundle 

GpiQueryCharBox, see Character 
bundle 


GpiQueryCharDirection, see 
Character bundle 

GpiQueryCharMode, see Character 
bundle 

GpiQueryCharSet, see Character 
bundle 

GpiQueryCharShear, see Character 
bundle 

GpiQueryCharStringPos, 70, 109 
GpiQueryCharStringPosAt, 70 
GpiQueryClipBox, see Clip region 
GpiQueryClipRegion, see Clip region 
GpiQuery Color, see Global attributes 
GpiQueryColorData, 148 
GpiQuery Colorlndex, 148 
GpiQueryCp, 111 
GpiQueryCurrentPosition, see 
Non-bundle attributes 
GpiQueryDefArcParams, see 
Attributes, default 
GpiQueryDefAttrs, see Attributes, 
default 

GpiQueryDefaultViewMatrix, 162 
GpiQueryDefTag, see Attributes, 
default 

GpiQueryDefViewingLimits, see 
Attributes, default 
GpiQueryDevice, 50 
GpiQueryDeviceBitmapFormats, 

127 

GpiQuery Dr awControl, 183 
GpiQueryEditMode, see Segment, 
editing 

GpiQueryElement, 176 
GpiQueryElementPointer, see 
Segment, editing 
GpiQueryElementType, see 
Segment, editing 
GpiQueryFonts, 105, 108 
GpiQueryFontMetrics, 105 
GpiQueryGraphicsField, 169 
GpiQuerylnitialSegmentAttrs, 181 
GpiQuery KerningPairs, 101 
GpiQueryLineEnd, see Line bundle 
GpiQueryLineJoin, see Line bundle 
GpiQueryLineType, see Line bundle 
GpiQueryLineWidth, see Line 
bundle 

GpiQueryLineWidthGeom, see Line 
bundle 

GpiQueryLogColorTable, 148 
GpiQueryMarker, see Marker bundle 
GpiQueryMarkerBox, see Marker 
bundle 

GpiQueryMarkerSet, see Marker 
bundle 

GpiQueryMetaFileBits, 196 
GpiQueryMetaFileLength, 196 
GpiQueryMix, see Global attributes 
GpiQueryModelTransformMatrix, 


158. See also Non-bundle 
attributes 

GpiQueryNearestColor, 148 
GpiQueryNumberSetlds, 109 
GpiQuery Page Viewport, 164 
GpiQueryPattem, see Area bundle 
GpiQueryPattemRefPoint, see Area 
bundle 

GpiQueryPattemSet, see Area 
bundle 

GpiQueryPel, 79 

GpiQueryPickAperturePosition, 191 
GpiQueryPickApertureSize, 190 
GpiQueryRealColors, 148 
GpiQueryRegionBox, see Regions 
GpiQueryRegionRects, see Regions 
GpiQueryRGBColor, 148 
GpiQuerySegmentAttrs, 181 
GpiQuerySegmentNames, see 
Segment, editing 
GpiQuery SegmentPriority, 180 
GpiQuerySegmentTransformMatrix, 
160 

GpiQuerySetlds, 109 
GpiQueryTag, see Non-bundle 
attributes 

GpiQuery Vie wingLimits, see 
Non-bundle attributes 
GpiQueryViewingTransformMatrix, 
161. See also Non-bundle 
attributes 

GpiQuery WidthTable, 101 
GpiRealizeColorTable, 127, 147 
GpiRectlnRegion see Regions 
GpiRemoveDynamics, 185 
GpiResetBoundaryData, 194 
GpiResetPS, 50 
GpiRestorePS, 50-51 
GpiRotate, 7 
GpiSaveMetaFile, 195 
GpiSavePS, 50-51 
GpiScale, 7 

GpiSetArcParams, see Non-bundle 
attributes 
GpiSetAttrs, 60 
GpiSetAttrMode, see Attribute 
mode 

GpiSetBackColor, see Global 
attributes 

GpiSetBackMix, see Global 
attributes 

GpiSetBitmap, 129, 132 
GpiSetBitmapBits, 129 
GpiSetBitmapDimension, see 
Bitmap dimension functions 
GpiSetBitmapId, 112 
GpiSetCharAngle, see Character 
bundle 

GpiSetCharBox, see Character 
bundle 
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GpiSetCharDirection, see Character 
bundle 

GpiSetCharMode, see Character 
bundle 

GpiSetCharSet, see Character 
bundle 

GpiSetCharShear, see Character 
bundle 

GpiSetClipPath, 96 
GpiSetClipRegion, see Clip region 
GpiSetColor, see Global attributes 
GpiSetCp, 111 

GpiSetCurrentPosition, 62. See also 
Non-bundle attributes 
GpiSetDefArcParams, see 
Attributes, default 
GpiSetDefAttrs, see Attributes, 
default 

GpiSetDefaultViewMatrix, 162 
GpiSetDefTag, see Attributes, 
default 

GpiSetDefViewingLimits, see 
Attributes, default 
GpiSetDrawControl, 183, 190 
GpiSetDrawingMode, 180-181 
GpiSetEditMode, see Segment, 
editing 

GpiSetElementPointer, see 
Segment, editing 

GpiSetElementPointerAtLabel, see 
Segment, editing 
GpiSetGraphicsField, 5, 169 
GpiSetlnitialSegmentAttrs, 181 
GpiSetLineEnd, see Line bundle 
GpiSetLineJoin, see Line bundle 
GpiSetLineType, see Line bundle 
GpiSetLineWidth, see Line bundle 
GpiSetLineWidthGeom, see Line 
bundle 

GpiSetMarker, see Marker bundle 
GpiSetMarkerBox, see Marker 
bundle 

GpiSetMarkerSet, see Marker 
bundle 

GpiSetMetaFileBits, 195-196 
GpiSetMix, see Globed attributes 
GpiSetModelTransformMatrix, 158. 

See also Non-bundle attributes 
GpiSetPageViewport, 154, 163-165 
during MetaFile recording, 201 
with PM_Q_STD print format, 234 
GpiSetPattem, see Area bundle 
GpiSetPattemRefPoint, see Area 
bundle 

GpiSetPattemSet, see Area bundle 
GpiSetPel, 79 

GpiSetPel, in retain mode 7 
GpiSetPickAperturePosition, 191 
GpiSetPickApertureSize, 190 
GpiSetPS, 46, 163 
during MetaFile recording, 201 


with PM_Q_STD print format, 
234 

GpiSetRegion, see Regions 
GpiS etS e gmentAttr s, 181 
GpiSetSegmentPriority, 180 
GpiSetSegmentTransformMatrix, 
160 

GpiSetStopDraw, 10, 184-185 
GpiSetTag, 192. See also 
Non-bundle attributes 
GpiSetViewingLimits, see 
Non-bundle attributes 
GpiSetViewingTransformMatrix, 
161, 200. See also Non-bundle 
attributes 

GpiStrokePath, 93-94 
GpiTranslate, 7 
GpiUnrealizeColorTable, 147 
GpiWCBitBlt, 89-90, 129, 132 


IBMNULL print driver, 224 
Icon, 130-131 

IMAGEBUNDLE, see Image bundle 
Image bundle, 6, 61, 84-85 
Image display, 132, 147 
Image functions, 84—85 
Image primitives, 85-90 
Instance transform, 160 
Internal prolog, 62, 160, 161-162 
Italic font simulation, 108 


Kerning, 101-104 


Lcid, see Set id 

Line bundle, 6, 58, 71-72. See also 
Geometric wide line attributes 
Line end attribute, 90—91 
Line functions, 71-79 
Line join attribute, 91 
Line primitives, 72 
Line type attribute, 71 
Line width attribute, 61, 71 
Line width geometric attribute, 90 
LINE BUNDLE, see Line bundle 
IMatch, see Font, match number 
Logical color table creation, 145—147 
Logical font creation, 107—109 


Marker box attribute, 83-84 
Marker bundle, 6, 61, 82-84 
Marker cell attribute, 83-84 
Marker functions, 82-84 
Marker primitives, 84 
Marker set attribute, 83 
Marker symbol attribute, 83 
MARKERBUNDLE, see Marker 
bundle 


Match number, see Font, Match 
number 

MATRIXLF structure, 157 
Matrix multiplication, 269—271 
Memory DC, 262 
Memory MetaFile, 195 
MetaFile, 195-218 
creation, 195 

differences from PM_Q_STD 
format, 222 

display as sub-picture, 200 
escape orders, 200—203, 280-282 
interchange with other systems, 
200 

internal structure, 272-282 
printing, 199, 204, 222 
rules for creation, 200-203 
S AA conforming, 200 
scaling to fit output area, 199 
recording in another MetaFile, 
199 

MetaFile functions, 195—199 
Micro-PS, 2, 49, 297-299 
Mix mode attribute: 
area, 79 

area background, 79 
character, 65 
character background, 66 
image, 85 

image background, 85 
line, 71 
marker, 82 

marker background, 83 
Mixed 32-bit and 16-bit 
applications, 256 
Model transform, 6, 158—161. See 
also Non-bundle attributes 
Multi-threaded applications, 10 


Network printing, 225-227 
Non-bundle attributes, 61—62 
Non-retained graphics, 8 
Non-retained only functions, 7 
Non-retained segments, 177, 183 
Normal-PS, 2, 49 


Order buffer, 175-176 

Orders: 

drawing, 172-176, 283-296 
extended, 174—175 
fixed 1 byte, 172 
fixed 2 byte, 173 
long, 173-174 

OD_DIRECTDC, see Device 
context, direct 

ODJNFO DC, see Device context, 
info 

OD_MEMORY DC, see Device 
context, memory 
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OD_METAFILE DC, see Device 
context, MetaFile 
OD_METAFILE_NOQUER;Y DC, 
see Device context, MetaFile 
OD_QUEUED DC, see Device 
context, queued 
OS/2 Version 2.0, 255-256 


Page dimensions 4, 47-48, 154, 
163-164 

Page units, 3-4, 48, 153-154, 
163-164 

recording in MetaFile, 201 
setting on GpiPlayMetaFile, 197 
Page viewport, 163-165 
Path areas, 92 
Path definition, 91-92 
Path outlines, 93 
Paths, 90—97 

Pattern origin attribute, 80 
Pattern set attribute, 79, 112 
Pattern symbol attribute, 80 
Piclchg function, 204 
Pick aperture, 190 
Pick identifier, 192. See also 
Non-bundle attributes 
PicPrint function, 204 
Picture functions, 7 
Picture function calls, 204 
Picture utilities, 204 
PIF files, 204 

PM_Q_RAW print format, 221, 222, 
260 

PM_Q_STD print format, 221-222, 
260 

differences from MetaFile, 222 
rules for creation, 233-234 
Point size of font, 98, 106 
Pointer, 128, 130-131 
Presentation driver, 1-2, 222-223 
Presentation space, 2, 43-49 
association, 45, 46, 49 
cached Micro-PS, 43-44, 45-46 
creation, 44, 46 
Micro-PS, 43, 44 
Normal-PS, 43, 44-45 
ownership, 2 

PrfQueryProfileString, 228, 229, 
230, 231, 233 

Primitive groups, 5. See also 
Attribute bundles 
Primitives, drawing, 5—6 
Print destination functions, 235 
Print job functions, 235 
Print queue processor, see Queue 
processor 

Print requester, 225-227 
Print server, 225-227 
Print subsystem, 222-224 
Printer, 219-254 


device name, 219, 228—229 
driver name, 229, 231 
fonts, 234-235 
installation, 224 
job property selection dialog, 

229- 230,231 
output to, 3 
port name, 229 

property selection dialog, 230 
queue name, 229, 230-231 
Printer pooling, 225 
Printer set up, 224-225 
Printer sharing, 225 
Printing, 219-254 
ASCII text, 219, 232 
direct, 219-220 
display screen, 232 
MetaFiles, 199, 204, 222 
monochrome, 265 
multiple copies, 263 
output area definition, 263 
queued, 220 
raw data, 219, 228, 232 
real size, 265 
scaled to fit, 264 
using base control program 
functions, 220 

using PM_Q_RAW format, 221, 

222 

using PM_Q_STD format, 
221-222, 233-234 
using Presentation Manager 
functions, 221-222, 227-232 
using printer selection method, 
228-230, 232 

using queue selection method, 

230- 231, 232 

using special formats, 222 
with zero translation, 165, 
265-266 

PS, see Presentation space 
Programs: 

area drawing, fig 1.8, 28-29 
BitBlt, fig 1.10, 32-33, figs 
5.3-5.5, 135-139 

BitBlt image with realizable color 
table, fig 5.6, 139-142 
bitmap, create and draw to, fig 
5.2, 133-134 

cached Micro-PS draw, fig 2.6, 57 
clip path definition, fig 3.18, 
96-97 

DevPostDeviceModes, fig 12.7, 
241, fig 12.12, 246 
DRIVDATA querying for queue, 
fig 12.11, 245 
error display using 

WinGetLastError, fig 1.14, 
38-40 

geometric wide line, fig 3.17, 
95-96 


GpiPartialArc, figs 3.9-3.10, 76, 

77 

kerning, fig 4.2, 102-103 
line drawing, fig 1.7, 26-27 
logical color table creation, fig 6.2, 
149 

logical font creation, figs 4.4-4.6, 
112-118 

marker drawing, fig 1.9, 30-31 
MetaFile examples, figs 
11.1-11.7, 204-218 
Micro-PS draw, figs 2.4—2.5, 54-56 
Normal-PS draw, fig 2.3, 51-53 
outline font scaling, figs 4.8-4.11 
120-125 

printer info, querying from INI 
file, figs 12.4-12.6, 236-240, 
figs 12.8-12.10, 244-245 
printer, output to, fig 1.3, 14—17 
printing raw data, fig 12.15, 
252-253 

printing to default queue, fig 
12.14, 249-251 

print queue processor querying, 
fig 12.16, 254 

retained segment operations, fig 
9.2, 178, fig 9.4, 188 
transformation, figs 1.11-1.13, 
34-38 

scale to fit window, fig 7.5, 

166-167 

set id allocation, fig 4.7, 119 
sub-picture display, fig 11.7, 
214-218 

text output, figs 1.4-1.6, 18-26 
translation removal, fig 7.6, 167 
window, output to, fig 1.2, 13-14 
WM_PAINT processing, fig 2.7, 58 
Prolog, see Internal prolog 
Psychometric RGB, 143, 147 


Queue destination functions, 235 
Queue driver, see Queue processor 
Queue name, 219, 229, 230 
Queue processor, 232—233, 261, 
263-266 

Queue selection method of printing, 
230-231 

Queued printing, 220 


Realizable color table, 132, 146, 
198-199 

Reference point, pattern, 80 
Region complexity, 171 
Region functions, 170 
Regions, 169-171 
Reset option on GpiPlayMetaFile, 
197, 198, 234 

Resource :functions of PS, 7 
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Responsiveness to end user, 10 
Retain mode, 180—181 
Retained graphics, 8 
Return codes, 11 
RGB color, 143 
Rop code, 87-88 
Rotation, see Transformation, 
rotation 


Scale-to-fit window, 165 
Scaling, 151 

Scaling, see Transformation, scaling 
Scrolling entire picture, 162 
Scrolling text, 4 
Segment, 176-178 
attributes, 181-182 
called, 179 
chained, 179 
content editing, 186—187 
creation, 176-177 
editing, 187 
non-retained, 177, 183 
priority, 180 

recording in MetaFile, 203 
retained, 177 
structure, 177 
unchained, 179 
zero id, 182-183 
Segment transform, 160-161 
Separator file, 227 
Set id: 

allocation, 109 
bitmap, 112 


character, 66 
font creation, 107 
GpiPlayMetaFile option, 197 
marker, 83 
pattern, 79 

Spooler, disabling, 220 
Spooler function calls, 222 
Stop draw, 184—185 
Strikeout font simulation, 108 
Sub-picture, drawing MetaFile as, 
200 

Sub-picture drawing using viewing 
transform, 161 
Suppress option on 

GpiPlayMetaFile, 197—198 
Symbol set, 204 


Tag, segment, 192—193 
Text, 6. See also Fonts 
Text functions, 65—71 
Text output to display, 4 
Text output to printer, 4-5 
Transformation, See also Transform 
matrix, operation 
about point, 152 
pipeline, 154—155 
rotation, 6—7, 150-151 
scaling, 7, 151, 162 
translation, 7, 151-152, 165 
Transform matrix: 
operation, 267-271 
order of concatenation, 154—155 
parameter format, 157 


TRANS FORM_ADD option, 156 
TRANSFORM_PREEMPT option, 
156-157 

TRANSFORMJREPLACE option, 
156 


Underscore font simulation, 108 


Viewing limits, 168. See also 
Non-bundle attributes 
Viewing transform 61, 62, 161-162, 
196 


WinBeginPaint, 42, 45 
Winding mode area fill, 81 
Window, output to, 3 
WinDraw functions, 7, 201 
WinEndPaint, 45 
WinFreeErrorlnfo, 12 
WinGetClipPS, 42, 45 
WinGetErrorlnfo, 12 
WinGetLastError, 12 
WinGetPS, 42, 45 
WinGetScreenPS, 42, 45-46 
WinLoadPointer, 128 
WinOpenWindowDC, 3, 41 
WinQueryWindowDC, 3, 41 
World coordinates, 152 
WM_PAINT processing, 45 

32-bit OS/2, 255-256 



VNR Computer Library 


computer science/graphics 


While OS/2 Presentation Manager offers a rich and powerful graphics interface, this complex 
package is not generally well understood. In this volume, IBM’s former GPI Development Team 
Leader for OS/2 1.1 clearly describes the Graphics Programming Interface for the current 
version of OS/2. 

Designed to supplement the IBM and Microsoft ™ manuals, this guide addresses both GPI 
and Device functions and their architectures. Graham C.E. Winn taps his extensive experience 
with the GPI to show how it can provide high-quality text and graphics output to displays and 
printers. He explains the full range of graphic functions from simple to complex, without use of 
complicated mathematics. 

Winn provides a detailed description of the Application Programming Interfaces, along with 
more than 60 programming examples that help answer many questions about GPI and Device 
functions. He covers use of the GPI to display text, characters, lines, curves, areas, markers, 
images, and more. Chapters on all the facets of GPI drawing from an application expand your 
understanding of: 

Fonts— public and private fonts, monospaced and proportional fonts, raster and outline 
fonts, font selection, logical font creation 

Bitmaps —bitmap formats, creation, deletion, selection, data transfer 

Color tables —the standard color table, logical color table creation, color queries 

Coordinate spaces and transformation —page units, matrix parameter formats, coordinate 

limits, model transform, viewing transform, default viewing transform, device transform 

MetaFiles —MetaFile printing, MetaFile-to-MetaFile recording, scaling MetaFiles to fit an 

output area, displaying a MetaFile as a subpicture, MetaFile restrictions 

Printing —queued printing, base control program printing, Presentation Manager printing, 

OS/2 print subsystem, printer installation and setup, form selection, printer fonts 

The author also explores the GPI’s less obvious function capabilities, limitations, and restric¬ 
tions. In addition, he helps clarify GPI operation through simple C programs that illustrate the 
functions in use. The C programs may be purchased separately on a diskette. 

Written by an IBM insider who has had extensive GPI involvement since its initial development, 
this reference will open the door to superior OS/2 graphics and serve as a valuable aid to 
application program developers. 

About the Author 

Graham C.E. Winn, Ph.D., has worked at IBM since 1974 on display and workstation software in 
both development and customer support roles. His involvement with Presentation Manager 
began in 1986, when he became Lead GPI Developer for IBM’s OS/2 Version 1.1. He has 
since worked as part of the team handling both service and non-defect questions relating to 
GPI and other areas. Dr. Winn has also taught the GPI part of IBM’s OS/2 programming class 
and presented a GPI seminar. He has written a number of journal articles and technical dis¬ 
closure bulletins, and holds a patent for a video display terminal with partitioned screen. He 
earned his Ph.D. and B.Sc. degrees at Southampton University in England. 
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